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2>REFACE 


Record Management Services for the PDP-11 (RMS-11) provides powerful 
jJata management capabilities. The RMS-1l User's Guide tells you about 
those capabilities and how to use them. This manual is designed as a 
reference for MACRO-1l11 programmers. 


RMS-11 is a set of software routines that transfers data between a 
running program, which uses data in a logical form called records, and 
the file processor portion of an operating system, which maintains the 
physical structure of the data on a storage device. 


NOTE 
You can use RMS-11 Indexed files only if you have purchased 


the RMS-11K software product. Your system manager can tell 
you if your system includes this capability. 


PREREQUISITES 

To read this manual, you should be a MACRO-11 programmer who has_ read 

and understood the RMS-11 User's Guide. 

STRUCTURE OF THE MANUAL 

Chapter 1 tells you how to use RMS-11 routines in a MACRO-11 _ pro- 
gram, including the minimum requirements and the order in 
which you must use them. 

Chapter 2 covers the means of providing buffer space for RMS-11l op- 
erations. 

Chapter 3 describes the fields of the File Access Block. 

Chapter 4 describes the fields of the Record Access Block. 

Chapter 5 describes the fields of the different types of Extended 
Attribute Blocks. 

Chapter 6 describes the fields of the Name Block. 

Chapter 7 describes the field access macros. 

Chapter 8 describes the file and record operation macros. 

Chapter 9 describes the use of Block I/O. 
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Appendixes provide supplementary information, Such as: 
RMS-11 success and error completion codes 
Sample RMS-11 programs 


Routine to convert 64-bit date-time information tc 
ASCII 


ASSOCIATED DOCUMENTS 

The RMS-11 documentation set contains the following manuals: 
RMS-11 User's Guide 
RMS-11 MACRO-11 Reference Manual 
RMS-11 Installation Guide 


You must also use operating system documentation. See the Documenta- 
tion Directory for your operating system. 
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DOCUMENTATION CONVENTIONS 


RMS-11 operates similarly on the supporting operating systems (see Ap- 
pendix A of the RMS-11l User's Guide). Therefore, it should be possi- 
ble to produce a single manual describing that operation. However, 
the differences among operating systems present a barrier to that un- 
ification. The following conventions are designed to enable you to 
hurdle that fence. 


DIFFERENCES IN OPERATING SYSTEM FUNCTIONS 


Details that are common to the operating systems are printed in black, 
and the details that are specific to one operating system or another 
are printed in color as follows: 


e RSTS/E-specific information is printed in red. 


e IAS-, RSX-11M-, and VAX-specific information is printed in blue. 


SYNTAX DESCRIPTIONS 


In the descriptions of macro usage, this manual includes a general 
form for each macro, using the following conventions: 


REQUIRED You must include all uppercase’ char- 
acters as shown. 


user-specific You substitute for lowercase characters 
information specific to your uSage. 


[may be used] You can, but do not have to include 
characters in brackets. The convention 
-»-] means the series can continue until 
it exhausts logical possibilities. 


Punctuation You must use punctuation as shown. 


The descriptions of user control block fields that contain numeric va- 
lues include minimum and maximum specifications. These are logical 
values and normally, are not equal to the physical minimum and maximum 
for the field. 


Additionally, a portion of a field, whether byte or word, described as 


"low order" or "least significant" is the portion with the lower ad- 
dress. 
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CHAPTER 1 


USING RMS-11 IN A MACRO-11 PROGRAM 


Record Management Services for PDP-1l operating systems (RMS-11) is a 
set of routines that enable programs to process files and records 
within files. The RMS-1l User's Guide describes the features of 
RMS-11. All capabilities supported by an operating system are avail- 
able to a MACRO-11 program. 


To obtain RMS-11 services at run time, your program must’ contain 
RMS-11 processing macros and user control blocks. The processing ma- 
cros are expanded at assembly time. The resulting code is executed at 
run time to perform the specified operation. Each macro represents a 
program request for a file- or record-related service. 


With every request for a service, information is exchanged between 
your program and the RMS-11 routines via user control blocks. These 
blocks are: 


Block Name Function 


File Access Block (FAB) Describes a file and contains 
file-related information. 


Record Access Block (RAB) Describes a Record Access Stre- 
am and the records being ac- 
cessed by that stream. 


Extended Attribute Block (XAB) Contains file attribute infor- 
mation beyond that in the FAB. 


Name Block (NAM) Describes a location in memory 
containing system-related in- 
formation about a file. 


Prior to issuing a request for an RMS~-ll service, your program must 
place information detailing the request in the associated control 
block. 


Example A request to open a file must be accompanied by the name or 
ID of the file, information on how the file will be ac- 
cessed, and details on how the file is to be shared. 


Example A program request to read a record from a file must’ specify 
an access mode and if appropriate, a key value identifying 
the desired record. 

After a request for service has been processed, RMS-ll uses the same 
control block to return information to your program. When a file has 
been successfully opened, RMS-11 provides attribute information such 
as the organization of the file and the format of the records in the 
file. After successfully retrieving a record from a file, RMS-11 pro- 
vides your program with the location in memory of the record and the 
length of the record. 

The amount of information exchanged between RMS-l1l and your program 

varies with the nature of the request and the attributes of the file 

being processed. 


To use RMS-11 routines in a MACRO-11 program, you must understand how 
tos: 


1. Declare the RMS-11 facilities that your program requires. 


2. Allocate and initialize user control blocks designed to communi- 
cate with RMS-1ll. 


3. Access fields in user control blocks at run time. 
4. Perform file and record operations. 


5. Assemble your program modules and task build them with the RMS-11 
routines. 


1.1 DECLARING RMS-11 FACILITIES 

Every program that processes RMS-11 files must contain directives and 
special-purpose macros that declare the RMS-11 facilities required at 
assembly and run time. To declare RMS-11 facilities that are used by 
your program, you must do the following: 

1. List RMS-11 macros in .MCALL directives. 

2. Declare the processing environment. 


3. Declare buffer pool requirements and techniques. 


4. Issue a SINIT or SINITIF macro. 


NOTE 


Unless otherwise noted, RMS-11 macros use decimal radix for 
numeric values. 


1-2 Using RMS-11 in a MACRO-11 Program 


1.1.1 Listing Names of Required Macro Definitions 


All macros used in your program must be listed as arguments in a 
-MCALL directive. Listing the macros in this way allows the actual 
code of each macro to be read in from the RMS-11 source macro library 
(RMSMAC.MLB) during assembly. 


General form: 
-MCALL arg[,arg]..] 


where arg is a symbolic name of a macro required in the assembly of 
your program. The macro names can be listed in any order. 


The number of .MCALL directives can be minimized because some macro 
definitions contain .MCALL directives. Table 1-1 contains the minimum 
-MCALL arguments that provide .MCALL directives for all RMS-11 macros 
that can be used in a program. 


Table 1-1: Minimum Set of .MCALL Arguments 


-MCALL Arguments Embedded .MCALL Arguments 


ORGS None. 










POOLSB Central buffer pool declaration macros. 


SINIT or SINITIF] None. 







Run-time field access macros (described in 
Chapter 7) and completion routine macros (des- 
cribed in this chapter). 


SGNCAL 


File Access Block allocation and initialization 
macros (described in this chapter), field offset 
macros (described in Chapter 3), and error code 
macros (described in Appendix A). 


Record Access Block allocation and initialization 
macros (described in this chapter), field offset 
macros (described in Chapter 4), and error code 
macros (described in Appendix A). 


Extended Attribute Block allocation and initiali- 
zation macros (described in this chapter), field 
offset macros (described in Chapter 5), and error 
code macros (described in Appendix A). 


Name Block allocation and initialization (des- 
cribed in this chapter), field offset macros 
(described in Chapter 6), and error code macros 
(described in Appendix A). 


SFBCAL File operation macros (described in Chapter 9). 


SRBCAL Record operation macros (described in Chapter 9). 
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As shown in Table 1-1, you can ensure that all RMS-11 macros used ina 
program appear as arguments in .MCALL directives by coding the follow- 
ing sequence of .MCALL directives and macro execution in that program: 


-MCALL ORGS, POOLSB,SINIT 

-MCALL SGNCAL,FABSB,RABSB, XABSB,NAMSB 
-MCALL SFBCAL, $SRBCAL 

SGNCAL 

SFBCAL 

SRBCAL 


By issuing the $GNCAL, S$FBCAL, and SRBCAL macros, you cause 
ded .MCALL directives to take effect. 


You can omit any macro names from .MCALL directives that do 
to a particular program. 


Example If the program does not use Name or Extended 
Blocks, do not include the NAMSB or XABSB macros. 


the embed- 


not apply 


Attribute 


You may also omit the $RBCAL or $FBCAL macros and list separately each 


file and record operation macros used by your program. 


NOTE 


If you are allocating control blocks in one module, 


but 


using field offset and/or error code macros in other mo- 


dules, in those modules you must: 


1. include one or more of the following arguments in .MCALL 


directives 
2. execute the specified macros, in the form: 


mMacnam RMSSL 


except SRMSTAT, which requires no argument when executed 


~MCALL Arguments Embedded Macro Definitions 
FABOFS FAB field offsets 
RABOFS$ RAB field offsets 
XABOFS XAB field offsets 
NAMOFS$ NAM field offsets 
SRMSTAT Error codes 
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1.1.2 Declaring the Processing Environment 


You must include one or more ORGS macros within the set of modules 
that you link together with the Task Builder to produce an executable 
task. All ORGS macros must be in modules that are part of the root of 
your task. An ORGS macro for a particular file organization must be 
present even if no record operations are performed when such a file is 
opened. 


The use of ORGS macros in your source modules enables the Task Builder 
to select for linking only those portions of RMS-11 required by your 
program*. Each ORGS macro declares a unique combination of file or- 
ganization and record operations. 

General form: 


ORGS org[,<recop[,recop...]>] 


where org is the type of file organization as one of the _ following 
symbolic values: 


IDX = Indexed file organization 
REL = Relative file organization 
SEQ = Sequential file organization 


recop is a symbolic value identifying a type of record operation 
that will be performed on a file of the specified organiza- 
tion. If a single value is included, the angle brackets are 
not needed. If multiple values are specified, you must en- 
close them in angle brackets and use commas to separate each 
value from the preceding value. 


One or more of the following symbolic values may be speci- 
fied in any order: 


CRE = file of specified organization may be created 
DEL = delete operation 

FIN = find operation 

GET = get operation 

PUT = put operation 

UPD = update operation 


Example The following code declares that one or more Sequential 
files will be created and put operation performed by the 
program. Additionally, one or more Indexed files will be 
opened and find, get, and update operations will be per- 
formed on those files. Finally, one or more Relative files 
will be opened, but no record operations will be performed: 
file operations may be performed. 


ORGS. SEQ,<CRE, PUT> 
ORGS IDX,<GET, UPD, FIN> 
ORGS REL 


*When you task build RMS-11 nonoverlaid. If you use an RMS-11 overlay 
structure, the ODL file specifies which RMS-11 modules are linked to 
your program. However, the ORGS macro still determines which of 
those routines your program can use. 
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1.1.3 Declaring Buffer Pool Requirements 


RMS-11 requires a collection of I/0 buffers and internal control 
structures. to support file processing at run time. The area in your 
program occupied by these buffers and control structures is known as 
the buffer pool. 


The major portion of the buffer pool is composed of I/O buffers. To 
your program, record processing under RMS-11l appears as the movement 
of records directly between a file and the program itself. However, 
RMS-11 actually uses I/O buffers as intermediate storage during data 
transfers: 


e When your program finds or gets a record, RMS-11 moves the block or 
bucket containing the record from the file to an I/O buffer. Then, 
on a get, RMS-11 moves the record from the buffer to your program. 


@e When your program puts, updates, or deletes a record, RMS-ll moves 
the specified data from your program to the I/O buffer. Then, for 
Relative and Indexed files, normally RMS-11 moves the bucket in the 
buffer out to the file immediately. However, for Sequential files 
and for Relative and Indexed files with Deferred Write specified, 
RMS-11 doesn't write out the buffer until it has to be used for 
another operation. 


The size of I/O buffers depends on the organizations of the files 
being processed, the number of files open simultaneously, and the 
number of simultaneously active Record Access Streams. In providing 
the information needed to calculate the size requirements for the I/0 
buffers portion of the buffer pool, you have three choices: 


l. <A centralized buffer pool controlled by RMS-1l. 


2. Private I/O buffers for one or more files plus a centralized pool 
controlled by RMS-11 for other requirements. 


3. A centralized buffer pool controlled by a routine you provide. 


When RMS-11 controls a centralized buffer pool, RMS-ll allocates I/0 
buffers as well as the internal control structures required for file 
processing from a single area in your program. Normally, this space 
is inaccessible to your program: RMS-11 totally manages the space 
within the pool and allocates portions, as needed, for buffer space 
and control structures for open files. 


You can also allocate private I/O buffers on a per-file basis by spec- 
ifying the address and total size of each buffer in fields of the File 
Access Block associated with a file. When the file is open, this 
buffer space is completely managed by RMS-11 and your program must not 
access it. However, when the file is closed, the private I/0 buffer 
Space is available for use by your program. 


The major advantage of private I/O buffers is avoidance of fragmenta- 
tion in a centralized buffer pool. Since particular files have vary- 
ing I/O buffer requirements based on their organization, a centralized 
buffer pool can reach the point where there is sufficient total space 
available for the opening of an additional file, but the space is not 
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contiguous. When such a situation arises, the specified file cannot 
be opened. 


Whether you let RMS-11 control a centralized buffer pool or _ specify 
private I/O buffers, RMS-11 always requires certain internal control 
structures that must be allocated in the buffer pool to support file 
processing. The number of internal control structures required by 
RMS-11 in the buffer pool is based on the organizations of the files 
being processed, the maximum number of files open simultaneously, and 
the maximum number of simultaneously connected Record Access Streams. 
Once again, your program must provide, at assembly time, the informa- 
tion needed to determine the size requirements of the internal control 
structures that must be allocated in the centralized buffer pool. 


The presence in your source modules of the macros listed in Table 1-2 
allows RMS-11 to determine the size requirements for your program's 
buffer pool. The macros are described in Chapter 2. If you want pri- 
vate I/0 buffers for one or more files, you can allocate these ona 
file-by-file basis, either statically (at assembly time) or dynamical- 
ly (at run time). Refer to the descriptions of the BPA (buffer pool 
address) and BPS (buffer pool size) fields in Chapter 3. 


Finally, you can assume total control over buffer space, allocating it 
when RMS-1l requires it, taking it back when RMS-11 no longer needs 
it. This facility, called Get Space Address (GSA), is complex and 
should not be used by most programmers. Chapter 2 also describes the 
requirements for the GSA routine. 


Table 1-2: Space Pool Declaration Macros 


POOLSB] Beginning of space pool declaration Yes 

PSBDB Number of Buffer Descriptor Blocks Yes 

PSFAB Number of files open simultaneously Yes 

PSRAB Nonindexed streams connected If Sequential or 
simultaneously Relative files 

PSRABX] Indexed streams connected If Indexed files 
simultaneously 

PSIDX | Number of defined keys If Indexed files 

PSBUF Input/output buffer requirements If no BPA or GSA 





POOLSE | End of space pool declaration Yes 
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1.1.4 Initializing the Processing Environment 


Your program must initialize the RMS-11 processing environment at run 
time before the program attempts an RMS-11 operation. You accomplish 
this with the SINIT or SINITIF macro. 


General form: 
SINIT or SINITIF 


The code generated by the SINIT macro unconditionally initializes 
RMS-11 internal control structures at run time. The SINITIF code, 
however, initializes the internal structures only if they have not 
been initialized during the current execution of the task. You use 
the SINITIF macro in program modules that can be the first to use 
RMS-11, but are not always run first. 


RMS-11 clears the Processor Status Word 0-Bit to indicate that ini- 
tialization was successful. Therefore, normally after SINIT, the 
0O-Bit is cleared; if the 0-Bit is set, an RMS-11l file was open when 
the macro was initiated and no initialization occurred. Normally 
after SINITIF, the 0-Bit is set; if the 0-Bit is cleared, the pro- 
cessing environment was previously initialized. 


If your program initiates any RMS-1l file or record operation before 
the environment is initialized, RMS-11 returns ERSINI error code. 
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1.2 USER CONTROL BLOCKS 


User control blocks are formatted buffers in your program's address 
space. Each control block consists of data fields that are used to 
exchange information between your program and the RMS-11 routines. 


You must allocate space for control blocks in your program at assembly 
time. You can also establish initial values for many of the data 
fields in these blocks at assembly time; or you can defer setting the 
contents of control block fields until run time. RMS-11 provides spe- 
cial macros that perform the functions needed to support control block 
allocation, assembly-time field initialization, and run-time field ac- 
cess. 


1.2.1 File Access Block (FAB) 


A File Access Block, abbreviated FAB, represents a file during the ex- 
ecution of file operation macros: 


SCLOSE 
SCREATE 
SDISPLAY 
SERASE 
SEXTEND 
SOPEN 


FAB fields (listed in Table 1-3) must contain the proper values before 
the macro is initiated, but they may be changed after the operation is 
complete because RMS-ll has transferred the pertinent information 
about the file to an internal (nonvisible) structure called an Inter- 
nal File Access Block (IFAB). 


Therefore, one FAB may be used to represent any number of files as 
long as the FAB is changed appropriately before each file operation is 
initiated. As a minimum you must ensure that the block is a valid FAB 
(BID and BLN fields contain the proper values) and that the FAB IFI 
field contains the value returned by RMS-11 when the file was created 
or opened. This value is the pointer to the IFAB. You should also 
set the FAB's fields to the values appropriate to the file operation 
you are preparing for: do not assume that the fields contain the va- 
lues you set before the last use. 


1.2.1.1 Allocation - Each FAB must be allocated at assembly time. 
The minimum syntax is: 


- EVEN 
label: FABSB 
FABSE 


where label is the name of the FAB and not necessarily the name of the 
file associated with the FAB. 


The FABSB macro allocates space for the FAB, and the FABSE macro 
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stores values in the individual FAB fields and terminates the defini- 
tion of the block. 


Table 1-3: File Access Block Fields 


Field| Field Default Description 
Name Size 


0 Size of file 

N/A FAB identifier 
l record Bucket size 

N/A RAB length 
Block size 
Location of private I/O buffer 
Size of private I/O buffer 
Available to user 
Automatic extension quantity 
Device characteristics 
Location of filespec defaults 
Size of filespec defaults 
Types of record operations 
Location of filespec 
Size of filespec 
File processing options 
Size of fixed area for VFC 
Pointer to IFAB 
Logical channel 
Maximum Record Number 
Maximum Record Size 
Pointer to NAM Block 
File organization 
Record attributes 
Record format 
Window size 
Clustersize 
File sharing 
Completion code 
More error information 
Pointer to first XAB 


0 
0 
0 
0 
0 
N/ 
0 
0 
G 
0 
0 
0 
0 


> 


Zz 
oooo™mw 
> 





*File attribute 


1.2.1.2 Initialization - The value stored in a FAB field by the FABSE 
macro is determined by an initialization macro, or in its absence, an 
RMS-11 default for the field (see "Initialization and Default" in the 
individual sections on the fields in Chapter 3). 
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If you want a field to contain a value other than its default value, 
you must specify its initialization macro between the FABS$B and FABSE 
macros*., Initialization macros have the general form: 


FSfnm arg 


where fnm is the three-letter field name, such as ALQ, MRN, and So on, 
and 


arg iS one or more arguments specifying the value(s) to be en- 
tered in the indicated field; arg can be a: 


e symbolic value, such as FBSPUT (representing put opera- 
tions), in the form FBSnam; symbolic values are joined 
together with exclamation points (!). 


® label, that is, the MACRO-11 term for the name of an ad- 
dress in the program, such as the start of a buffer. 


@e numeric value, such as maximum record size, specifying 
the number of bytes, characters, blocks, and so on. 


Cautions: 


e Because initialization macros operate at assembly time, you cannot 
use global symbols or labels as arguments. All symbols and labels 
must be defined locally, that is, in the same module with the ma- 
cros. 


e The default radix for numeric values in initialization macros is 
decimal. 


1.2.2 Record Access Block (RAB) 


A Record Access Block, abbreviated RAB, represents a Record Access 
Stream during the execution of record operation macros: 


SCONNECT 
SDELETE 
SDISCONNECT 
SFIND 
SGET 

SPUT 
SUPDATE 
SREWIND 
STRUNCATE 
SF LUSH 
SNXTVOL 


The RAB not only completely describes the format of the records in- 
volved, but also all other aspects of record operations. 


*The value of any field can also be set at run time by the field ac- 
cess macros SSET and SSTORE; see Chapter 7. 
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RAB fields (listed in Table 1-4) must contain the proper values before 
the stream is set up (via the SCONNECT macro) and before record opera- 
tions are initiated, but they can be changed after each operation is 
complete because RMS-1l has transferred the pertinent information 
about the stream to an internal (nonvisible) structure called an 
Internal Record Access Block (IRAB). 


Therefore, one RAB may be uSed to represent any number of streams as 
long as the RAB is changed appropriately before each record operation 
is initiated. As a minimum you must ensure that the block is a_ valid 
RAB (BID and BLN fields contain the proper values) and that the RAB 
ISI field contains the value returned by RMS-11 when the stream was 
connected to a file. This value is the pointer to the IRAB. You 
Should also set the RAB's fields to the values appropriate to the re- 
cord operation you are preparing for: do not assume that the fields 
contain the values you set before the last use. 


1.2.2.1 Allocation —- Each RAB must be allocated at assembly time. 
The minimum syntax is: 


» EVEN 
label: RABSB [type] 
RABSE 


where label is the name of the RAB, and 


type indicates if the program will attempt asynchronous I/0 op- 
erations using the RAB (see Chapter 1), with one of the 
following values: 


SYN means synchronous record operations only 


ASYN means both synchronous and asynchronous” record 
operations 


The RABSB macro allocates space for the RAB, and the RABSE macro 
stores values in the individual RAB fields and terminates the defini- 


tion of the block. 


1.2.2.2 Initialization - The value stored in a RAB field by the RABSE 
macro is determined by an initialization macro, or in its absence, an 
RMS-11 default for the field (see "Initialization and Default" in the 
individual sections on the fields). 


If you want a field to contain a value other than its default value,. 

you must specify its initialization macro between the RABSB and RABSE 

macros*., Initialization macros have the general form: 

*The value of any field can also be set at run time by the field ac- 
cess macros S$SET and SSTORE; see Chapter 7. 
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R$fnm arg 


where fnm is the three-letter field name, such as KBF, RAC, and so on 


arg is one or more arguments specifying the value(s) to be en- 
tered in the indicated field; arg can be a: 


@e symbolic value, such as RBSKEY, specifying a random re- 
cord operation, in the form RBSnam; two or more symbol- 
ic values are joined together with exclamation points 


(!). 


e label, that is, the MACRO-11 term for the name of an ad- 
dress in the program, such as the start of a buffer. 


@e numeric value, such as maximum record size, specifying 
the number of bytes, characters, blocks, and so on. 


Cautions: 


Because initialization macros operate at assembly-time, you cannot 
use global symbols or labels as arguments. All symbols and labels 
must defined locally, that is, in the same module with the macros. 


The default radix for numeric values in initialization macros is 
decimal. 


Table 1-4: Record Access Block Fields 


F 


Field Default Description 





RAB identifier 

Relative record number or VBN 
RAB length 

User area 

FAB address 

Pointer to IRAB 

Key buffer address 

Key of reference 

Key buffer size 
Multiblock count 
Multibuffer count 

Record Access Mode 
Address of output record 
Record's File Address 
Fixed control area buffer 
Record processing options 
Size of output record 
Completion status code 
Status value 

Input record buffer 

Input record buffer size 


Z2=z 


0 
0 
0 
0 
0 
0 
0 
0 
0 
0 
/ 
f 
0 
0 
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1.2.3 Extended Attribute Block (XAB) 


An Extended Attribute Block, abbreviated XAB, is an extension of the 
File Access Block for an RMS-1l file. An XAB represents one of the 
following during file operations: 


Area (Indexed only) 

Key (Indexed only) 

Date-time information 

Protection information 

Summary information (Indexed only) 


XABS are generally required only when a file is created, particularly 
if the file is Indexed, or when the SDISPLAY macro is used to retrieve 
information about a file. 

XAB fields (listed by XAB type in Chapter 5) must contain the proper 
values before the operation is initiated, but they may be changed 


after each operation is complete because RMS-11 has transferred the 
pertinent information about the file to the appropriate IFAB. 


1.2.3.1 Allocation - Each XAB must be allocated at assembly time. 
The minimum syntax is: 


- EVEN 
label: XABSB type 
XABSE 
where label is the name of the XAB, and 
type indicates the type of information contained in the XAB and 

therefore its structure and fields, with one of the fol- 

lowing values: 
XBSALL the XAB defines a file area 
XBSDAT the XAB contains date-time information 
XBSKEY the XAB defines a key for an Indexed file 
XBS$PRO the XAB specifies file protection information 


XBSSUM the XAB contains summary information about an 
Indexed file 


A type must be specified, or the MACRO assembler will gen- 
erate an error. 


The XABS$B macro allocates space for the XAB, and the XABSE macro 


stores values in the individual XAB fields, including the type symbol- 
ic value in the COD field, and terminates the definition of the block. 
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1.2.3.2 Initialization - The value stored in an XAB field by the 
XABSE macro is determined by an initialization macro, or in its ab- 
sence, an RMS-1l default for the field (see "Initialization and De- 
fault" in the individual sections on the fields). 


If you want a field to contain a value other than its default value, 
you must specify its initialization macro between the XABS$B and XABSE 
macros*. Initialization macros have the general form: 


xXSfnm arg 
where fnm is the three-letter field name, such as IAN, RDT, and so on 


arg is one or more arguments specifying the value(s) to be en- 
tered in the indicated field; arg can be a: 


@® symbolic value, such as XBSNUL, representing null _ key 
specification, in the form XB$nam; two or more symbolic 
values are joined together with exclamation points (!). 


e label, that is, the MACRO-11 term for the name of an ad- 
dress in the program, such as the start of a buffer. 


@e numeric value, such as fill number, specifying the 
number of bytes, characters, blocks, and so on. 


Cautions: 


e Because initialization macros operate at assembly-time, you cannot 
use global symbols or labels as arguments. All symbols and labels 
must be defined locally, that is, in the same module with the ma- 
cros. , 


e The default radix for numeric values in initialization macros is 
decimal. 


1.2.3.3 Linking and Ordering XABs - Whenever you want to include Ex- 
tended Attribute Blocks in a file operation, you must link them with 
the File Access Block and with each other. This linking is done with 
pointers, addresses stored in the FAB XAB field and then in each of 
the XAB NXT fields; the end of the chain is indicated by a zero NXT 
field. 


1.2.3.3.1 Ordering by Type of XAB - Within a chain of XABs, RMS-11 
does not require any ordering by type, that is, the contents of the 
COD field. 


ee a a en ee ee a a 


*The value of any field can also be set at run time by the field ac- 
cess macros S$SET or SSTORE; see Chapter 7. 
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Example 


To determine the attributes of a 


allocate, at assembly time, one each: 


Type 


Date XAB 
Key XAB 
Protection 
Summary XAB 


You can link these blocks together in several ways; 


them are: 


1. 


DS PFAB: 


DATXAB: 


KEYXAB: 


PROXAB: 


SUMXAB: 


2 
MOV 
SSTORE 


MOV 
SSTORE 
MOV 
SSTORE 
MOV 
SSTORE 
MOV 
SSTORE 


Finally, 


XAB 


. EVEN 
FABSB 
XSXAB DATXAB 
FABSE 
XABSB XBSDAT 
XSNXT KEYXAB 
XABSE 
XABSB XBSKEY 
XSNXT PROXAB 
XABSE 
XAB$B XBSPRO 
XSNXT SUMXAB 
XABSE 
XABSB XBSSUM 
XABSE 


#DS PFAB, R4 
#S UMXAB, XAB, R4 


#S UMXAB, R4 
#KEYXAB,NXT,R4 
#KEYXAB, R4 
#DATXAB ,NXT,R4 
#DATXAB, R4 
#PROXAB,NXT,R4 
#PROXAB, R4 
#0,NXT,R4 


you issue a $DISPLAY 


Label 


DATXAB 
KEY XAB 
PROXAB 
SUMXAB 


=e 


=e 


me 


single-key 


Indexed f 


two 


At assembly time, with initialization macros: 


POINT TO FIRST XAB 


POINT TO NEXT XAB 


POINT TO NEXT XAB 


7; POINT TO NEXT XAB 


At run time, with the $STORE macro: 


; PUT FAB ADDRESS IN R4, 


REQUIRED 


=e 


MAKE DIFF XAB 1ST IN 


CHAIN 
; PUT XAB ADDRESS IN R4 
; LINK IN NEXT XAB 
; PUT XAB ADDRESS IN R4 
; LINK IN NEXT XAB 
; PUT XAB ADDRESS IN R4 
; LINK IN NEXT XAB 
; PUT XAB ADDRESS IN R4 
; LINK IN NEXT XAB 
macro Chapter 8) 


(see 
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RMS-11 fills the XAB chain with attribute information, set- 
ting fields in accordance with the COD field of each block. 


1.2.3.3.2 Ordering Within XAB Type - Multiple instances of Key and 
Allocation XABs must be linked: 


e In ascending order by contents of a numbering field, that is, the 
REF and AID fields respectively 


e Logically contiguous, that is, there can be no XABs of other’ types 
within a series of Key or Allocation XABs 


e Densely for the $CREATE operation, that is, the XABS must be num- 
bered 1, 2, 3, and so on; by contrast, the numbering for SDISPLAY, 


SEXTEND, and SOPEN does not have to be dense; that is, you can se- 
lect only certain keys or areas whose attributes you want set 


1.2.4 Name Block 


A Name Control Block, abbreviated NAM, contains system-specific infor- 
mation about a file, including: 


Full File Specification 
An ASCII string representing RMS-11's merger of: 


e the primary file name string described by the FAB FNA and 
FNS fields 


e the default name string described by the FAB DNA and DNS 
fields 


e the system defaults 


File ID 
An index that the file processor can use to locate a file 
without consulting directories; must be used with device 
ID. 


Device ID 
An indicator for the device containing the file; Must be 
used with file ID. 


RMS~11 provides this information in NAM Block fields (listed in Table 
1-5) during create and open operations and uses this information as 
input during erase and open operations. 


You indicate the existence of a NAM Block for these services by set- 
ting the FAB NAM field to the address of a properly allocated NAM 
Block. NAM Block fields must contain the proper values before the op- 
eration is initiated, but they may be changed after the operation is 
complete. 
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1.2.4.1 Allocation - Each NAM Block must be allocated at assembly 
time. The minimum syntax is: 


. EVEN 
label: NAMSB 
NAMSE 


where label is the name of the NAM Block. 


The NAMSB macro allocates space for the NAM, and the NAMSE macro 
stores values in the individual NAM fields and terminates the defini- 
tion of the block. 


1.2.4.2 Initialization - The value stored in a NAM field by the NAMSE 
macro is determined by an initialization macro, or in its absence, an 
RMS-11 default for the field (see “Initialization and Default" in the 
individual sections on the fields). 


If you want a field to contain a value other than its default value, 
you must specify its initialization macro between the NAMSB and NAMSE 
macros*, Initialization macros have the general form: 


NSfnm arg 


where fnm is the three-letter field name, such as ESA, ESL, and So on, 
and 


arg is one or more arguments specifying the value(s) to be en- 
tered in the indicated field; arg can be a: 


e label, that is, the MACRO-11 term for the name of an ad- 
dress in the program, such as the start of a buffer. 


e numeric value, such as expanded string size, specifying 
the number of bytes. 


Cautions: 


e Because initialization macros operate at assembly time, you cannot 
use global symbols or labels as arguments. All symbols and labels 
must be defined locally, that is, in the same module with the ma- 
cros. 


e The default radix for numeric values in initialization macros is 
decimal. 


*The value of any field can also be set at run time by the field ac- 
cess macros $SET and SSTORE; see Chapter 7. 
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Table 1-5: NAM Block Fields 


Field | Field Default Description 
Name i 


Device ID 
Expanded string address 
Expanded string length 
Expanded string size 
File ID 























1.3 CONTROL BLOCK FIELD ACCESS AT RUN TIME 


RMS-11 field access macro retrieve, modify, and test the contents of 
fields in the RMS-11 control blocks, FABs, RABs, and XABs, at run 
time. These macros enable you to treat the control block fields as 
logical entities, without regard for the placement of the fields with- 
in the control blocks and to a large degree, for the sizes of the 
fields. 


Table 1-6 contains a summary of the available macros. Each macro is 
also described in a separate section of Chapter 7. 


Table 1-6: RMS-11 Field Access Macros 


Macro Name Field Size Function 


SCOMPARE 1 byte or 1 word Compares the contents of a field 
with a value you specify. 


SFETCH Any size Copies the contents of a field into 
a location you specify. 


SOFF 1 byte or 1 word Resets one or more bits within a 
bit string field. 


SSET 1 byte or 1 word Sets one or more bits within a bit 
string field. 


SSTORE Any size Copies the contents of a location 
you specify into a field. 


STESTBITS 1 byte or 1 word Tests one or more bits within a bit 
string field. 











NOTE 


RMS-11 assumes octal radix for all numeric values used as 
operands for the field access macros. You indicate decimal 
radix with an explicit decimal point following a numeric 
value. 
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1.4 FILE AND RECORD OPERATIONS 


You use the RMS-11 file and record operation macros to access and man- 
ipulate files and records within files. These macros combine with the 
control blocks (Chapters 3 through 6) to form your program's run-time 
interface with RMS-ll. 


Before executing one of these macros, your program sets values in a 
control block's fields, then specifies the block as an argument to the 
macro. The macro initiates all processing involved with the indicated 
RMS-1l operation. During the operation, RMS-11 returns information 
about the processing in fields of the associated control block. 


If you do not initialize or set fields, relying on defaults, RMS-11 
changes the fields to contain the default or minimum values as output 
from the operation. 


See the RMS-11 User's Guide for a description of the operations them- 
selves. 


While differing in function, the file and record operation macros’ use 
the same general format and calling sequence. Within the calling se- 
quence, you identify the control block associated with the operation 
and optional completion routines. 


Before your program initiates a file or record operation macro, it 
must: , 


1. Ensure that the appropriate values are set in the fields used by 
RMS-11 during the operation. You do this with either initializa- 
tion macros (see Chapters 3, 4, and 5) or field access macros (see 
Chapter 7). 


2. Execute the correct calling sequence, 


1.4.1 Completion Routines 


You can write subroutines that RMS-11 executes as an extension of a 
file or record operation macro. These completion routines can be used 
after the successful completion or after error termination of an oper- 
ation. 


RMS-11 invokes a completion routine if you supply an address at the 
appropriate point in the calling sequence for the operation. At the 
end of the completion routine, RMS-11 restores the stack and _ other 
parameters and returns control to your program at the point after the 
macro was initiated. 


The use of completion routines is always optional. However, if you do 
not use completion routines, your program should check the value of 
the associated block's STS field after the macro has been executed. 
If the status code is negative, an error occurred during the opera- 
tion. If the status code is positive, the operation was successful, 
although an STS value greater than one indicates qualified success. 


Weina PMG-11 in a MACRO—11 Proaram 1-19 


See Appendix A for a description of the completion codes. The STS 
field should never contain zero after an RMS-1l1l operation. 


When using completion routines, you must be aware of conventions in 
the following areas: 


Register Usage 
General register R5 contains the address of the same argu- 
ment list or a copy of the argument list, that was part of 
the calling sequence to the RMS-11 operation (see Section 
8.0.2). Therefore, you can use the control block address at 
2(R5) to access fields in the control block. 


RMS-11 Operations within Completion Routines 
A completion routine can execute file and record operation 
macros. Each operation is an extension of the original op- 
eration that caused the completion routine to be used. See 
Appendix A of the RMS-11 User's Guide for restrictions on 
this capability in the RMS-11 Asynchronous Environment. } 


To return control from a completion routine to RMS-1l, your. program 
must do the following: 


1. Restore the stack pointer (SP) to its value at the beginning of 
the completion routine. Your program must not attempt to cause 
control flow changes by modifying the stack. 


2. Execute a SRETURN macro, in the form: 
SRETURN 


This macro requires no arguments and denotes the end of a comple- 
tion routine. 


1.4.2 Calling Sequence 


Each file and record operation macro requires a word-aligned formatted 
argument list. Your program can construct this list or allow RMS-11 
to build it. Generally, your program generates less code and use less 
stack to build the list than does RMS-11l. 


1.4.2.1 Your Program Supplies the Argument List - If your program 
constructs the argument list, it executes RMS-11 file and record oper- 
ations with the following sequence: 
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The program constructs the argument list in the following form, 
with the arguments arranged in the order shown: 


Argument Size RMS-11 Interpretation 
Undefined 1 byte Not used. 
Argument Count 1 byte Binary value from 1 through 3 repre- 


senting the number of arguments to 
be used from the argument list. 
This field equals 1 if you do not 
supply completion routine addresses. 


Block Address 1 word Address of a FAB for file operations 
or a RAB for record operations. 

Error Address 1 word Address of a completion routine you 
want called if the operation fails. 

Success Address 1 word Address of a completion routine you 


want called if the operation com- 
pletes successfully. Not used by 
file operation macros. 


Store the address of the argument list in general register R5. 


Execute the file or record operation macro without arguments, in 
the form: 


Smacnam 
If completion routines were specified, continue processing because 


success and/or failure has been tested and handled. Otherwise, 
check the STS field of the associated control block. 


Example The following code constructs an argument list and uses it 


to execute a get operation: 


MOV #LIST,R5 ADDRESS OF ARGUMENT LIST 

SGET 7;READ A RECORD FROM THE FILE 
LIST: «WORD 3 ;NUMBER OF ARGUMENTS 

-WORD INRAB ;RECORD ACCESS BLOCK ADDRESS 

- WORD ERR1 ;ERROR ROUTINE ADDRESS 


-WORD succl ;SUCCESS ROUTINE ADDRESS 


Example The following code constructs an argument list specifying a 


success completion routine, but no error completion routine: 


LIST: - WORD 3 
»WORD INRAB 
-WORD -1 7NO ERROR ROUTINE 
-WORD succl 
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Example The following code constructs an argument list specifying 
error and success routines, but the program determines be- 
fore the operation is initiated that neither routine 


applies: 
MOV #1,LIST ;SHRINK SIZE OF LIST 
MOV #LIST,R5 ;ADDRESS OF ARGUMENT LIST 
SGET 7;READ A RECORD FROM THE FILE 
SCOMPARE #0,STS,2(R5) ;LOOK AT STATUS CODE 
BGT NXTSTP ;SUCCESS 
GETERR: . 
LIST: -WORD 3 ;NUMBER OF ARGUMENTS 
«WORD INRAB 7;RECORD ACCESS BLOCK ADDRESS 
~ WORD ERR1L ;ERROR ROUTINE ADDRESS 


-WORD SUCC1 ;SUCCESS ROUTINE ADDRESS 


1.4.2.2 RMS-11 Generates the Argument List - Your program can execute 
RMS-11 file and record operation macros with the form: 


Smacnam block[,error[,success] ] 


where block is the address of a FAB for file operations or a RAB for 
record operations. 


error is the address of a completion routine you want called if 
the operation fails. 


success is the address of a completion routine you want called if 
the operation completes successfully. Not used by file 
operation macros. 


The macro builds an argument list on your program's stack from the in- 
formation provided. Then it initiates the processing appropriate to 
the indicated operation. After the macro is executed, your. program 
should check the STS field of the associated block unless completion 
routines were specified. 


1.4.3 File Operation Macros 

A file operation macro causes RMS-11 to perform an action related _ to 
an entire file. The macro name indicates the type of operation per- 
formed. The fields of the FAB associated with the macro in the cal- 
ling sequence identifies the file and qualifies the operation. 


Table 1-7 summarizes the RMS-11 file operation macros. 
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Table 1-7: RMS-11 File Operation Macros 


Macro Name Description 


SCLOSE Closes an open RMS-11 file so that your program can 
longer access its contents. 


SCREATE RMS-11 creates and opens an RMS-11 file as described by 
the associated FAB and XABs, if any. 


SDISPLAY Stores attributes of an existing RMS-11 file in FAB and 
XAB fields. 


SERASE Deletes an existing RMS-11 file and removes its entry(s) 
from a directory. 


SEXTEND Increases the number of blocks allocated to an RMS-11 
file. 


SOPEN Opens an existing RMS-11 file, making its contents ava- 
ilable for processing. 





1.4.4 Record Operation Macros 


After it has created or opened an RMS-11 file, your program can _ per- 
form record operations on it. These operations involve the following 
concepts that are explained in the RMS-11 User's Guide and Chapter 1 
of this manual. 


Record Access Streams 

File sharing 

Context, Current Record, and Next Record 
Synchronous and asynchronous record operations 


Table 1-8 summarizes the RMS-11l record operation macros. 


1.5 CREATING THE TASK 


After you have written a MACRO-11 program as described in this 
chapter, you must assemble each module with the following reference in 
your command string: 


LB: [{1,1]RMSMAC.MLB/ML 


After you have assembled all modules in your program successfully, you 
must link the modules with the RMS-11 routines using the Task Builder 
utility supplied with your operating system. You can link the RMS-11 
routines in your task without overlays or with disk-resident or 
memory-resident overlays. See the RMS-11l User's Guide for a discus- 
sion of these options. 
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NOTE 


Do not use the /SQ switch with the Task Builder. RMS-1ll re- 
quires PSECTS to be in alphabetical order. 


Table 1-8: RMS-11 Record Operation Macros 









Macro Name Description 







SCONNECT Establishes a Record Access Stream. 





Deletes a record from an RMS-l1l Relative or Indexed 
file. 


SDELETE 





SDISCONNECT 






Terminates a Record Access Stream. 







SFIND Locates a record in an RMS-1l file. 


SFLUSH Moves all data in unwritten I/O buffers to disk. 







SFREE Unlocks a bucket locked by a Record Access Stream. 


SGET Moves a record from an RMS-ll file into your program's 


user buffer. 








SN XTVOL Continues processing with the next volume of magnetic 


tape multivolume set. 





SPUT Moves a record from your program's user buffer to an 


RMS-11 file. 





SREWIND Resets a Record Access Stream's context | to the logical 


beginning of an RMS-11 file. 







STRUNCATE Deletes record at the end of an RMS-l11l Sequential 


file. 






SUPDATE Replaces a record in an RMS-11 file with a record from 


your program's user buffer. 






SWAIT Suspends processing until an RMS-11 asynchronous” re- 


cord operation completes. 
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CHAPTER 2 


PROVIDING BUFFER SPACE 


2.1 CENTRAL BUFFER POOL 

The central buffer pool must be allocated at assembly time with the 
series of macros and arguments described in this section and Table 
2-1. The macro series must start with the POOLSB macro and end _ with 
the POOLSE macro. 

You can use multiple buffer pool allocations among the program modules 
that you link together with the Task Builder utility. The Task Build- 


er sums the size requirements indicated by all buffer pool declara- 
tions. 


Table 2-1: Buffer Pool Declaration Macros 


POOLSB | Beginning of buffer pool declaration Yes 
PSBDB Number of Buffer Descriptor Blocks Yes 
PSFAB Number of files open simultaneously Yes 


PSRAB Number of nonIndexed streams If Sequential or 
connected simultaneously Relative files 


PSRABX | Number of Indexed streams If Indexed files 
connected simultaneously 


PSIDX Number of defined keys If Indexed files 


PSBUF Input/output buffer requirements If no BPA or GSA 





POOLSE | End of buffer pool declaration Yes 


REKKEKKKKKEKKER 


* * 
REQUIRED * PSBDB * 
* * 
KEKKKKKEKKKEKSE 


2.1.1 PSBDB 


The PSBDB macro ensures that the buffer pool contains sufficient space 
for internal RMS-11l control structures’ known as Buffer Descriptor 
Blocks (BDBSs). 


General form: 
PSBDB nbrbdbs 


where nbrbdbs is a numeric value or symbol representing the number of 
Buffer Descriptor Blocks required to support the file 
processing performed by your program. 


To determine this value, use the following equation: 
nbrbdbs = maxbuf + maxrel + (2 * maxidx) 


where maxbuf is the count of the I/0 buffers that can be used simul- 
taneously, that is, the maximum number of I/0 buffers 
ever in use for simultaneously open files. 


You calculate this value by totaling the multibuffer 
counts in the MBF fields of RABs for all combinations of 
simultaneously connected Record Access Streams. The max- 
imum value among all such combinations is the desired 
maxbuf value. RMS-11 must allocate one BDB for each I/0 
buffer being used at one time. 


Maxrel is the maximum number of Record Access StreamsS ever con- 
nected simultaneously for put operations to Relative 
files (whether or not an actual put operation is per- 
formed). RMS-11 allocates one BDB for each stream con- 
nected to a Relative file. 


maxidx is the maximum number of Record Access StreamS ever ac- 
tive simultaneously for put operations to Indexed files 
(whether or not an actual put operation is performed). 
RMS-11 allocated one BDB for each stream connected to an 
Indexed file. 
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KREKEKEKKKEKKEKE 


* * 

REQUIRED * PSFAB * 
* * 

KREKKEKKKEKEKKEKEE 


2.1.2 PSFAB 


The PSFAB macro ensures that the buffer pool contains sufficient space 
for internal RMS-11 control structures related to File Access Blocks 
(FABS). 

General form: 


PSFAB number 


where number is a numeric value or symbol representing the maximum 
number of files that are open simultaneously at run time. 
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RKKKKKKKKEKKEER 
* * 


ai PSRAB * 
* * 


RKEKKKKRKKRKRKEEK 


2.1.3 PSRAB 


The PSRAB macro ensures that the buffer pool contains sufficient space 
for internal RMS~-11 control structures related to Record Access Blocks 
(RABS) for Sequential and Relative files. You can omit this pool 
macro if your program does not perform record operations on Sequential 
or Relative files. 


General form: 
RSRAB number 
where number is a numeric value or symbol representing the maximum 


number of RABs that your program connects simultaneously 
to Sequential and Relative files. 
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KRRKKKEKKEKKEESE 


* x 
*  PSRABX * 
* * 
TTT TT Tree TT 


2.1.4 PSRABX 


The PSRABX macro ensures that the buffer pool contains sufficient 
space for internal RMS-11 control structures related to Record Access 
Blocks (RABs) for Indexed files. You can omit this pool macro if your 
program does not perform record operations on Indexed files. 


General form: 
PSRABX rabs,keysiz,nbrkeys 


where rabs is a numeric value or symbol representing the maximum 
number of Record Access Streams that your program connects 
to Indexed files simultaneously. 


keysiz is a numeric value or symbol representing the size, in 
bytes, of the largest key field that can be accessed by one 
of the streams. 


nbrkeys is a numeric value or symbol representing the number of 
keys that can change values during an update operation on 
an Indexed file. You must specify this value whenever your 
program creates or opens an Indexed file with FBSUPD set in 
the FAB FAC field. 


Example The following code indicates that there will be at most one 
stream connected to an Indexed file at any point during pro- 
gram execution. The largest key field in any such file is 
32 bytes and no keys can change during update operations. 


POOLSB ;BEGIN POOL DECLARATION 
PSRABX 1,32 ;ONE FILE AND BIGGEST KEY, NO CHANGES 
POOLSE 7END POOL DECLARATION 
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KREKEKKKEKEKKEKKEEE 


* * 
* PSIDX * 
* k 


RREKKEKKEKKKKEKKEK 


2.1.5 PSIDX 


The PSIDX macro ensures that the buffer pool contains sufficient space 
for internal RMS-11 control structures containing summary information 
about an Indexed file's keys. You can omit this pool macro if your 
program does not open Indexed files. 


General form: 
PSIDX number 
where number is a numeric value or symbol representing the _ total 
number of keys defined for all Indexed files open simul- 


taneously. Include all keys even if they are never used 
for find or get operations. 


2-6 The POOL Macros 


KRKEKKEKEKKEKREKREEE 


* * 
*  PSBUF * 
* * 
RAEKEKKKEKEREKREESR 


2.1.6 PSBUF 
The PSBUF macro ensures that the buffer pool contains sufficient space 
for the I/O buffers required by your program. You can omit this macro 
only if you are providing private buffers for all files or a GSA rou- 
tine. 
General form: 
PSBUF iosiz 
where iosiz is a numeric value or symbol representing the total bytes 
required for I/0 buffers by your program. To calculate this number, 
use the following equation and round the result up to a multiple of 
four. 
iosiz = strmszl + strmsz2 +... + strmszn 
where iosiz is the total I/O buffer requirement, and 
strmszl are the I/O buffer space requirements (in bytes) for the 
Record Access Streams associated with the file that are 
strmszn active simultaneously. 
You calculate the requirements for each stream as follows: 
e For Sequential files on disk: STRMSZ = 512*MBC 
e For Sequential files on magnetic tape: STRMSZ = BLS 
where BLS is the size, in characters, of each physical block of the 
mMagtape file, that is, the value contained in the BLS field of the 
FAB, and 


MBC is the value contained in the MBC field of the RAB associated 
with the stream. 


e For Relative files: STRMSZ = BKS*512 


where BKS is the number of blocks in a bucket of the file (from the 
FAB BKS fields). 


e For Indexed files: STRMSZ = BKS*MBF*512 


where BKS is the number of blocks in the largest bucket of the file 
(selected from the FAB BKS and the Allocation XAB BKZ fields), and 


MBF is the value contained in the MBF field of the RAB associated 
with the stream. 
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2.2 GET SPACE ROUTINE 


A Get Space routine gives you complete control over the allocation of 
buffer space in your task. A single GSA routine serves all files used 
by the program. 


RMS-11 uses the GSA routine when it requires or releases space. When 
RMS-ll requests space, it expects one of two outputs from your 
routine: 


@ the low-byte address of a contiguous block of bytes at least as big 
as that requested. 


e an error indication that space is not available. RMS-11l issues an 
ERSDME message and returns control to the program. 


When RMS-11 releases space, it expects no output from your’ routine; 


it assumes that the release of space was successful if the routine 
terminates successfully. 


NOTES 
e Your routine must start on a word boundary: precede the 
label defining the routine's starting address with a 
~EVEN directive. 
e RMS-11 trusts your routine: it performs no parameter 
checking when the routine finishes and therefore can be 


lead into an error or even fatal situation if the routine 
did not allocate space properly. 


2.2.1 Specifying a Routine 
You can specify the starting address of your GSA routine at assembly 
time or at run time. Either way, your routine is used only when the 


internal address maintained by RMS-11 is not zero. Your program can 
also query RMS-11 at run time for the Get Space Address it is using. 


2.2.1.1 Specifying a Get Space Address at Assembly Time - 
General form: 
GSAS label 


where label is the name of your GSA routine as specified in the label 
field of a source line and followed by a colon. 


Example GSARTN: - 


RTS PC 


=e 


GSAS$ GSARTN 
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2.2.1.2 Specifying a Get Space Address at Run Time - 
General form: 
SSETGSA argument 

where argument is suitable as an operand for a MOV instruction. Where 
you use label with the $GSA macro, you use #label with 
the SSETGSA macro. You cannot use R6 aS an argument; 
the assembler returns the error message: 

»~ERROR ; R6 MUST BE RO — R5; 
Example GSARTN: . 


RTS PC 


=e 


SSETGSA #GSARTN 
Example SSETGSA R5 
Example SSETGSA 10(SP) 


Example SSETGSA 10(R3) 


2.2.1.3 Retrieving a Get Space Address at Run Time - 
General form: 
SGETGSA 
RMS-11 sets general register RO equal to the Get Space Address it has 


stored internally. If you have not executed a GSAS or SSETGSA macro, 
this value is 0. 


2.2.2 Interfaces to Routines 


The following subsections describe the interfaces between RMS-11 and 
your GSA routine as well as the format of RMS-11 pool block headers. 


RMS-11 sets a value in general register 2 (R2) to indicate whether: 

@e space should be allocated for an operation (R2 = 0) 

e space is being returned after an operation (R2 <> 0) 

The GSA routine is analogous to the $RQCB/SRLCB request and release 


core blocks routine as far as RMS-1l is concerned; the interfaces are 
identical. See also "Comments" below. 
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2.2.2.1 RMS-11 Request For Space - RMS-1l1l calls the routine with the 
following inputs: 


RO = address of RMS-11 Pool List Head 


Rl 


amount of space requested (in bytes) 
R2 = 0 
RMS-11 expects the following outputs from the user routine: 


If C-bit 
RO 


0, all bytes requested have been allocated and 
address of allocated block 


If C-bit = 1, Space was not available 


General registers R3, R4, R5, and R6 and the stack must contain the 
same values when the user routine finishes as they did when it was 
called. 


2.2.2.2 RMS-11 Release Of Space - RMS-11 calls the routine with the 
following inputs: 


RO = address of RMS-11 Pool List Head Block 
Rl = size in bytes of block being released 
R2 = address of block being released 


No outputs are expected: the user routine must complete the release; 
however, general registers R3, R4, R5, and R6 and the stack must con- 
tain the same values when the routine finishes as they did when it was 
called. 


2.2.2.3 RMS-11 Pool Block Header Formats - The RMS-11 buffer pool is 
actually subdivided into pools for each of the different sized inter- 
nal structures that RMS-11 must maintain: 


Buffer Descriptor Blocks 
Key Descriptor Blocks 
Internal FABs and RABs 
I/O Buffers 

Key Buffers 


Each of these pools is described with a Pool List Head that points to 
the first free contiguous block of bytes within the pool. 


Within all pools, space is divided into contiguous sections of bytes 
called blocks. Each block starts with a block header containing a po- 
inter to the next free block in the pool and its own size in bytes. 

Each pool is therefore accessed via the Pool List Head (which points 
to the first free block), then via a linked series of block headers 
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(which point to the next free block as well as tell how many bytes are 
in the block). 


RMS-11 Pool List Head Block: 


eee See ie 0 <-- (RO) 
| | 

| value | 
~---------- 2 

| | 

| 0 | 

| | 

eee ne 4 


e if value = 0, there is no available space left in the pool des- 
cribed by this List Head 


e if value <> 0, value points to the first available pool block 
header 


RMS-11 Pool Block Header: 


----------- 0 
| | 
| value | 
| | 
------+----+ 2 
| | 
| size | 
wann-=----- 4 


where value is either zero (0) or not: 


e if value = 0, this is the last available block in this 
pool 


e if value <> 0, value points to the next available pool 
block 


size is the size in bytes of this pool block including’ the 
four-byte header 


2.2.3 Comments 


e You must write the GSA routine and include it in the program. The 
referenced routine is NOT part of RMS-1ll. 


e Your routine does not have to use the RMS-11 Pool List Head Block, 
but is responsible for its upkeep if it does. 
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e If your routine does not allocate enough space for the impending 
operation, but signals RMS-11 that it has, the operation will fail 
in an unpredictable manner. 


e Since your own routine could fail to allocate enough space and sig- 
nal such failure to RMS-1l, causing a dynamic memory error, your 
program should check for the ERSDME error code after every file and 
connect operation. 


e Your routine could utilize the system routines S$RQCB and S$RLCB_ to 
accomplish the required functions, as follows: 


GSARTN: TST R2 ; CHECK RMS-11 REQUEST 
BNE 2$ 
JMP SROCB ; RMS-11 WANTS MORE SPACE 
2$: JMP SRLCB ; RMS-11 WANTS TO RETURN SPACE 


The JMP instruction allows the system routine to return directly to 
RMS-1l. 


e Your routine, when requested to allocate space, could use $RQCB as 
a subroutine (via JSR) to check if enough space is currently avail- 
able: 


-- if it is, $ROCB allocates it, returning with the C-bit = 0 
-- if it is not ($RQCB fails; C-bit = 1), your routine could: 


* extend the task 
* cannibalize other pools 


then allocate space out of the new room, set RO as a pointer’ to 
the allocated buffer, and return to RMS-1l1. 


e The space allocation and release procedures used by your. routine 
must be symmetrical. For instance, the system routines $RQCB and 
SRLCB round all sizes up to a multiple of four bytes; these rou- 
tines are symmetrical in that respect. If your routine employs one 
of these procedures, but not the other, the substitute must conform 
to this rounding standard. 
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CHAPTER 3 


FILE ACCESS BLOCK 


The initialization macros (this chapter) and the field access macros 
(Chapter 7) are provided so that you do not have to know the specific 
position and to a large extent, the size of each field in a FAB. You 
can, therefore, treat the fields as logical entities. It is also pos- 
sible that the positions and sizes of the fields will change from re- 
lease to release of RMS-1ll. 


However, you can determine the position of any field in a FAB as an 
offset from the FAB's starting address. RMS-ll represents these off- 
set values with symbols in one of the following forms: 
e OSfnm 
where fnm is the three-letter name of a one-byte or one-word field; 
fnm is the name used to reference the field in the initialization 
and field access macros. 
Example OSSTS for the status code field 
e oSfnmx 
where fnm is the name of a multiword field; fnm is the name used 
to reference the field in the initialization and field 


access macros. 


x is a number associated with an individual word in the 
field, from 0 through the end of the field. 


Example OSALQO for less significant word and QSALQ1 for the more 
Significant word in the ALQ field 


The values of these symbols can be found in the symbol table of an as- 
sembly listing file for any module containing the FAB. 


Table 3-1: File Access Block Fields 


Field Field Default Description 
Name Size 


Size of file 





Hy ar FAB identifier 

1B 1 record Bucket size 

1B N/A RAB length 

lw 0 Block size 

1W 0 Location of private I/0 buffer 
lw 0 Size of private I/O buffer 
lw 0 Available to user 

1W 0 Automatic extension quantity 
1B N/A Device characteristics 

lw 0 Location of filespec defaults 
1B 0 Size of filespec defaults 

1B FBSGET Types of record operations 
1w 0 Location of filespec 

1B 0 Size of filespec 

lw 0 File processing options 

1B 0 Size of fixed area for VFC 
1W N/A Pointer to IFAB 

1B 0 Logical channel 

2W 0 Maximum Record Number 

lw 0 Maximum Record Size 

1W 0 Pointer to NAM Block 

1B FBSSEQ File organization 

1B 0 Record attributes 

1B FBSVAR Record format 

1B 0 Window size 

1B 0 Clustersize 

1B 0 File sharing 

lw N/A Completion code 

lw N/A More error information 

lw 0 Pointer to first XAB 


*File setpibute 
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3.1 ALQ 


The two-word Allocation Quantity (ALQ) field contains the size (allo- 
cation quantity) of a disk file, in blocks. RMS-11 ignores the field 


for magnetic tape files. 


3.1.1 Use 


Input to: 


SCREATE 


You set the ALO field equal to the number of blocks to be 


allocated in the initial extent of the file. 


SEXTEND 


You set the ALQ field equal to the number of blocks 


added to the file. 
Output from: 


SOPEN 


to be 


RMS-11 sets the ALQ field equal to the virtual block number 
of the last block in the existing file; this is also the 


number of blocks in the file. RMS-11 obtains this 


informa- 


tion from the file attributes. RMS-11 updates attributes 


during SCREATE and an implicit or explicit file 


extension. 


RMS-11 uses only the attributes for this information: any 


blocks allocated to the file by non-RMS-11 tasks 


is essen- 


tially invisible to RMS-11; however, when RMS-11 extends 


the file, those blocks quickly satisfy the request. 


SEXTEND 


RMS-11 sets the ALO field equal to the number of blocks that 


were added to the file. 


3.1.2 Input Values 


SCREATE 


MINIMUM = 0, meaning that the actual size of the file, when it is 


created, depends on the file organization: 


e Sequential files are created with four blocks. 


File Access Block (FAB): 
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e Relative and Indexed files are created with an 
allocation four times bucket size. 


MAXIMUM = number of free blocks on the device containing the 
file; specifying a larger value results in error code 

ERSFUL 

SEXTEND 

MINIMUM = 1, meaning that one block should be added to tthe _ file 
(although a zero extent is possible, it is not logi- 

cal) 
MAXIMUM = number of blocks on the device containing the file; 


specifying a larger value results in error code ERSFUL 


For Relative and Indexed files, RMS-11l rounds values up to multiple of 
bucket size. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (See Chapter 7). 


3.1.3 Initialization and Default 
Macro takes the form: 
FSALQ numeric 
where numeric is a number of blocks as discussed under "Values." 


If there is no initialization macro, ALQ = 0. 


3.1.4 Comments 


If Allocation XABs are linked to the FAB, the create and extend opera- 
tions ignore the FAB ALQ field and obtain allocation quantities from 
the XABs; see Chapter 8. However, the open operation works as_ des- 
cribed. 
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* * 
* BID * 
* * 
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3.2 BID 

The FABSB macro sets the one-byte Block Identifier (BID) field to’ the 

File Access Block identifier, with the symbolic value of FBSBID. 
CAUTION 


DO NOT CHANGE THE BID FIELD. 


3.2.1 Use 


Before RMS-1l1 uses a FAB during a file operation, it verifies that the 
block is avalid FAB; one of the checks examines the BID field. If 
this field does not contain the proper code, RMS-11 aborts the opera- 
tion with an ERSFAB error code. 
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3.3 BKS 


The one-byte Bucket Size (BKS) field contains the size of a bucket, in 
disk blocks, for a Relative or Indexed file. The field has no meaning 
for Sequential files. 


3.3.1 Use 


Input to: 


SCREATE 
You set the BKS field equal to the number of disk blocks in 
a bucket for the file to be created, if the ORG field con- 
tains either FBSREL or FBSIDX*. 


Output from: 


SOPEN 
RMS-11 sets the BKS field equal to the bucket size esta- 
blished for the file when it was created, if the ORG field 
contains either FBSREL or FBSIDX*. RMS-11 obtains the _ in- 
formation from the file attributes. 


3.3.2 Input Values 


MINIMUM 0, meaning that RMS-11 calculates a size so that a_ bucket 


contains at least one record. 


MAXIMUM = number of blocks allowed by the operating system (specifying 
a larger value results in error code ERSBKS): 


IAS = 32 blocks 
RSTS/E = 15 blocks 
RSX-11M = 32 blocks 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (See Chapter 7). 


*If the file is Sequential, RMS-11 ignores the field during SCREATE 
and sets it to zero during SOPEN. 
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3.3.3 Initialization and Default 


Macro takes the form: 


FSBKS numeric 


If there is no initialization macro, BKS = minimum number of blocks to 


contain one record. 


3.3.4 Comments 


If Allocation XABs are linked to the FAB, the create and extend op- 
erations ignore the FAB BKS field and obtain bucket size(s) from 
the XAB(s); see Chapters 5 and 8. 

See the RMS-11 User's Guide for a discussion on bucket sizes. 


Records may not span bucket boundaries. 
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* * 
* BLN * 
* * 
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3.4 BLN 
The FABSB macro sets the one-byte Block Length (BLN) field to the File 
Access Block length, with the symbolic value of FBSBLN. 

CAUTION 


DO NOT CHANGE THE BLN FIELD. 


3.4.1 Use 


Before RMS-11l uses a FAB during a file operation, it verifies that the 
block is avalid FAB; one of the checks examines the BLN field. If 
this field does not contain the proper code, RMS-11 aborts the opera- 
tion with a ERSBLN error code. 
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* * 
RAEKKKRREEKKRKEKKE 


3.5 BLS 


The one-word Block Size (BLS) field contains the physical block size* 
in characters for a Sequential file stored on MAGNETIC TAPE only. 


3.5.1 Use 


Input to: 


SCREATE 
You set the BLS field equal to the number of characters per 
physical block in the magtape file to be created. RMS-11 
rounds this number up to the next multiple of four before it 
creates the file and sets up an I/O buffer. 


Output from: 


SOPEN 
RMS-11 sets the BLS field equal to the size of the physical 
blocks in the’ file existing on magtape. RMS-11 obtains the 
information from the file label on tape. If the information 
is not in the label, RMS-11 uses the default block size of 
the device. 


3.5.2 Input Values 


If you intend to use magtape to transfer data to a non-PDP-11l computer 
system, note the following: 


e If the destination is another DIGITAL system, block size should be 
less than or equal to 512 characters. 


e If the destination is a non-DIGITAL system, block size should be 
less than or equal to 2048 characters. 


*A block on magnetic tape is the data between interblock gaps. block 
size is expressed in characters; the representation of a character 
on tape is determined by the tape formatting standard. 
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MINIMUM = 0, at run-time RMS-11 interprets a value of 0 as the _ oper- 
ating system default: in all systems covered by this 
manual, the default is 512 characters. 

= 18, the smallest valid block size allowed by magtape device 
driver software 

MAXIMUM = 8192 characters 


A value can be set in the field with the initialization macro shown be 
or with the $STORE field access macro (see Chapter 7). 


3.5.3 Initialization and Default 
Macro takes the form: 
FSBLS numeric 


If there is no initialization macro, BLS = 0. 
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* BPA bi 
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3.6 BPA 


The one-word Buffer Pool Address (BPA) field points to an area in your 
program set aside for use as an I/0 buffer for all Record Access Stre- 
ams connected to the file represented by the FAB. If the address is 
zero, you are allocating the I/O buffer in some other way (see 
Chapters 1 and 2). 


3.6.1 Use 


Input to: 
SCREATE/SOPEN 


e If you want to specify a private buffer for the current 
file access (open to close), store the buffer's address 
in the BPA field before you open the file; also store 
the size of the buffer in the BPS field. 


e If you are not using a private buffer, ensure that the 
BPA field is zero; otherwise, RMS-1l interprets the 
value in the field as an address and tries to use the 
buffer indicated: the results are unpredictable. 
Output from: 
SCLOSE 


RMS-11 sets the BPA field equal to the address of the 
private buffer pool it is returning for your use. 


3.6.2 Input Values 
BPA must contain either: 


e zero (0) = there is no private buffer for this file; all space is 
allocated by RMS-11 from the central pool or by your GSA routine 


e address of the first byte of a private buffer for the file; the 
buffer must begin on a word boundary 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 
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3.6.3 Initialization and Default 


Macro takes the form: 


FSBPA label 


If there is no initialization macro, BPA = 0. 


3.6.4 Comments 


If you are uSing a private buffer for the file's I/0 buffer, you 
still have to allocate space in the central buffer pool for the 
internal structures (BDBs, IFAB, and so on) associated with the 
file; see Chapter 2. 


Once you have assigned a private buffer to a file in a FAB and 
opened that file, you cannot use that space until the file is 
closed. 
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3.7 BPS 
The one-word Buffer Pool Size (BPS) field contains the size, in bytes, 
of the private buffer indicated by the BPA field. RMS-11 uses this 
value to calculate the ending address of the private buffer. 
CAUTION 
RMS-11 does no further checking of the memory area defined 


by the FAB’ BPA and BPS fields. RMS-11 uses all the space 
allotted if it needs it. 


3.7.1 Use 


Input to: 
SCREATE/SOPEN 
If BPA is equal to zero, RMS-1l ignores the BPS field; if 
BPA is not equal to zero, that is, you are providing a pri- 
vate buffer, you must set the BPS field equal to size of 
that buffer in bytes. 
Output from: 
SCLOSE 


RMS-11 sets the BPS field equal to the size of the _ private 
buffer it is returning for your use. 


3.7.2 Input Values 
BPS must contain either: 
@e any value* if the BPA field is zero 


@e size of the private buffer for the file, in bytes, as a multiple of 
two 


To calculate the size of the private buffer, use the equation: 


BPS = strmszl + strmsz2 + ... + strmszn 


*Recommended value is the default, zero. 
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where BPS is the size of the private buffer, 


strmszl are the I/O buffer space requirements (in 


bytes) for 


strmsz2 the Record Access Streams associated with the file that 
- are active simultaneously. You calculate the require- 


strmszn ments for each stream as follows: 
-- For Sequential files on disk: strmsz 


-- For Sequential files on magnetic tape: 


512*MBC 


strmsz = BLS 


where BLS is the size, in characters, of each physi- 
cal block of the magtape file, that is, 


the value contained in the 
the FAB, and 


BLS field of 


MBC is the value contained in the MBC field of 
the RAB associated with the stream. 


-- For Relative files: strmsz = BKS*512 


where BKS is the number of blocks in a bucket of the 
file (from the FAB BKS fields). 


-~ For Indexed files: strmsz = BKS*MBF*512 


where BKS is the number of blocks in 


the largest 


bucket of the file (selected from the FAB 
BKS and the Allocation xXAB BKZ fields), 


and 


MBF is the value contained in the MBF field of 
the RAB associated with the stream. 


A value can be set in the field with the initialization 


macro shown 


below or with the SSTORE field access macro (see Chapter 7).. 


3.7.3 Initialization and Default 
Macro takes the form: 
FSBPS numeric 


If there is no initialization macro, BPS = 0. 
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3.7.4 


INBUF: 


MASTER: 


Examples 


- EVEN 
- BLKB 


FABSB 


FSBPA 
FSBPS 


FABSE 


4096. 


INBUF 
4096 
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3.8 CTX 
The one-word User Context (CTX) field is not used by RMS-1l, but is 


made available to you to contain any information you want associated 
with the file during run time. 


3.8.1 Use 


Anything you want. For example, you might use the CTX field to com- 
municate with a common completion routine. 


3.8.2 Input Values 
Anything you want, as long as it fits in 16 bits. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


3.8.3 Initialization and Default 
Macro takes the form: 

FSCTX argument 
where argument is any value you want. 


If there is no initialization macro, CTX = 0. 
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3.9 DEQ 


The one-word Default Extension Quantity (DEQ) field contains’ the 
number of blocks RMS-11 requests whenever it automatically extends the 
file (opposed to the explicit extend operation). RMS-11l requests ad- 
ditional blocks from the operating system* whenever a task attempts a 
put or update operation and there is not enough room in the file re- 
presented by the FAB to complete the operation. For Relative and In- 
dexed files, RMS-11 rounds DEQ up to the nearest multiple of bucket 
size before requesting the extension. 


3.9.1 Use 


Input to: 


SCREATE 
You set the DEQ field equal to the number of blocks’ that 
should be requested in each automatic extension of the file 
to be created. 


SOPEN 
You set the DEQ field equal to the number of ‘blocks to be 
used by RMS-1l1 as a temporary default extension quantity 
until the file is closed; the file attribute is not 
changed. 


Output from: 


SOPEN 
If the DEQ field is zero, RMS-11 sets it equal to the number 
of blocks established as the default extension quantity when 
the file was created. 


3.9.2 Input Values 


Default extension quantity should be a multiple of bucket size for. Re- 
lative and Indexed files. 


MINIMUM = 0, meaning that whenever RMS-11 has to extend the file, it 
requests five blocks for Sequential files and four times 


*Automatic extension can fail; see "Comments." 
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bucket size for Relative and Indexed files. 


MAXIMUM = 65,535 blocks 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


3.9.3 Initialization and Default 


Macro takes the form: 


FSDEO numeric 


If there is no initialization macro, DEQ = 0. 


3.9.4 Comments 


If Allocation XABs are linked to the FAB, RMS-1l uses the FAB DEQ 
value as a file default extension quantity, substituting it whe- 
never an area has to be extended automatically and the XAB DEQ 
field for that area is zero. 


Automatic extension can fail for at least the following reasons; 
there might be others: 


-- Operating system is RSTS/E and file is: 


contiguous; error code = ERSPRV 
shared; error code = ERSPRV 


-- No more room is available on the storage device; error code = 
ERSFUL 


On the RSTS/E operating system, file allocation is done in 
clusters; see the RMS-11 User's Guide for a discussion of the in- 
teraction between clusters and default extension quantity. 


See the RMS-11 User's Guide for a discussion of default extension 
quantity and its optimization. 
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The one-byte Device Characteristics (DEV) field contains a bit string 


indicating 


the generic characteristics of the device containing the 


file represented by the FAB. 


3.10.1 Use 


Output from: 


SCREATE/SOPEN 
RMS-11 sets the field equal to the appropriate device indi- 
cator. You can use field access macros (see Chapter 7) to 


examine the field. 


3.10.2 Output Values 


The DEV field contains one or more of the following symbolic values: 


FBSCCL 


FBSMDI 


FBSREC 


FBSSDI 


FBSSQD 


FBSTRM 


Carriage control device, such as printer or terminal 
Multiple-directory-structured device, such as a disk with 
a Master File Directory and at least one User File Direc- 
tory 

Unit record device, such as a terminal or line printer; 
all unit record devices are considered to be Sequential 
in nature 


Single-directory device, such as a disk with a Master 
File Directory, but no User File Directories present 


Sequential, block-oriented device, that is, magnetic tape 


Terminal device with keyboard and hard- or soft-copy out- 
put 
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3.11 DNA 


The one-word Default Name String (DNA) field points to an ASCII string 
containing the program-specific defaults for file specifications. 
During the file open process, if the file name string indicated by the 
FNA field is not a complete file specification, RMS-11 examines the 
DNA field. If it is not zero, RMS-11 uses the string indicated to 
supply the missing components. If DNA is zero, or not all the de- 
faults are supplied by the DNA string, RMS-ll uses the system de- 
faults. 


3.11.1 Use 


Input to: 
SCREATE/SOPEN 


e If you want to specify a default name string for a _ file 
operation, store the string's address in the DNA field 
before you initiate the operation; also store the _ size 
of the string in the DNS field. 


e If you are not using a default name string, ensure that 
the DNA field is zero; otherwise, RMS-l1l interprets the 
value in the field as an address and tries to use the 
string indicated: the results are unpredictable. 


3.11.2 Input Values 
The DNA field must contain either: 
e zero (0) = there is no default name string 


e address of the default name string. This string may contain values 
for one or more of the following file specification components: 


device 

account 

file name 

File type 

file extension 

version number 

protection code 
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The string must be written in ASCII notation, that is, with the 
eASCII/.ASCIZ MACRO-11 directive. 


A value can be set in the field with the initialization macro shown 
below or with the SSET field access macro (see Chapter 7). 


3.11.3 Initialization and Default 
Macro takes the form: 
FSDNA label 


If there is no initialization macro, DNA = 0. 


3.11.4 Examples 
To set up a default device specification: 


ANYFAB: FABSB 


FSDNA DEFDEV 
FSDNS 3 


FABSE 


DEFDEV: .ASCII /SY:/ 


3.11.5 Comments 

e The default name string may include logical names. 

@e RMS-11 checks the DNA string validity during each create and open 
operation. RMS-11 returns an error if it finds a bad component 
even if the FNA string supplies a valid value for that component. 


e See also FNA discussion about file specifications, parsing sequence 
on RSTS/E, and so on. 
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3.12 DNS 


The one-byte Default Name String Size (DNS) field contains tthe size, 
in bytes, of the default name string indicated by the DNA field. 


3.12.1 Use 


Input to: 
SCREATE/SOPEN 
If the DNA field is zero, RMS-11 ignores the DNA field; if 
the DNA field is not zero, that is, you are providing a de- 


fault name string, you must set the DNS field equal to. the 
size of that string in bytes. 


3.12.2 Input Values 
The DNS field must contain either: 
@e any value*, if the DNA field is zero 


e the size of the default name string, in bytes, with a maximum of 
255 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


3.12.3 Initialization and Default 
Macro takes the form: 
FSDNS numeric 


If there is no initialization macro, DNS = 0. 


*Recommended value is the default, zero. 
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3.13 FAC 

The one-byte File Access (FAC) field contains a bit string indicating 
the types of record operations that may be performed on the file re- 
presented by the FAB. This declaration enables RMS-11 to set up 
transfer vectors to the appropriate RMS-11 routines. RMS-11 rejects 


any record operation that was not specified in the FAC field when’ the 
file is opened (error code ERSFAC). 


3.13.1 Use 


Input to: 
SCREATE 
You set the FAC field to indicate all operations your. pro- 
gram performs on the file during the current access (open to 
close). 


NOTE 


The FAC field must contain at least FBSPUT. 


SOPEN 
You set the FAC field to indicate all operations your pro- 
gram performs on the existing file during the current access 
(open to close). 


3.13.2 Input Values 
FAC may contain one or more of the following symbolic values: 
FBSDEL SDELETE operations 
FBSGET SGET and/or $FIND operations 
FBSPUT SPUT operations 
FBSREA SREAD Block I/O operations (see Chapter 9) 


FBSTRN STRUNCATE operations: valid for Sequential files only 


File Access Block (FAB): FAC 3-23 


FBSUPD SUPDATE operations 


FBSWRT SWRITE Block I/O operations (see Chapter 9) 


If you want to specify more than one operation, you must concatenate 
the values uSing an exclamation point (!). 


A value can be set in the field with the initialization macro shown 
below or with the SSET field access macro (see Chapter 7). 


3.13.3 Initialization and Default 


Macro takes the form: 


FSFAC symbolic[!symbolic...] 


If there is no initialization macro, FAC = FBSGET. 


3.13.4 Comments 


If the file is an ANSI magtape file, RMS-1l automatically positions 
the tape at the end of the file when it is opened, unless the FOP 
field contains FBSNEF. 


Since the FAC field is a bit string, values cannot be added to the 
field with the $STORE field access macro. You should use the $SET 
field access macro (see Chapter 7). However, you use the S$STORE 
macro to (re)set all bits in the field. 


If you specify FBSDEL, FBSTRN, and/or FBSUPD, but do not include 
FBSGET, RMS-11 activates that capability anyway. Delete, truncate, 
and update operations must be preceded by a successful find or get 
operation. 


3-24 File Access Block (FAB): FAC 


KEKKEKKKKKRKEKKK 


* * 
* FNA * 
k * 
REKKEKKKKKKKEK 


3.14 FNA 


The one-word File Name String Address (FNA) field points to the ASCII 
string that is the file specification of the file represented by the 
FAB. RMS-11 examines the string indicated, if FNA is not zero. If 
any file specification components are missing from the string, or FNA 
is zero, RMS-ll checks the DNA field. If DNA is not zero, RMS-11 uses 
the string indicated to fill in the filespec; if DNA is zero, or the 
string indicated is not sufficient, RMS-11 inserts system default va- 
lues into the file specification. Then it passes the complete files- 
pec to the operating system to either open or create, then open, a 
file by that name. 


3.14.1 Use 


Input to: 
SCREATE/SOPEN 


e If you want to specify a file specification for a file 
operation, store the specification's address in the FNA 
field before you initiate the operation; also store the 
size of the specification in the FNS field. 


e If you are not using a file specification*, ensure that 
the FNA field is zero; otherwise, RMS-11l interprets the 


value in the field as an address and tries to use _ the 
string indicated: the results are unpredictable. 


3.14.2 Input Values 

FNA must contain either: 

e zero (0) = there is no file specification 

@e address of file specification string for the file 


The string must be written in ASCII notation, that is, with the 
-ASCII/.ASCIZ MACRO-11 directive. 


*I£ you are using all defaults, program and/or system, to define the 
file specification, or file ID to identify the file without a file 
specification (see Chapter 8). 
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A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


3.14.3 Initialization and Default 


Macro takes the form: 


FSFNA label 


If there is no initialization macro, FNA = 0. 


3.14.4 Comments 


File specifications contained in the FNA-indicated buffer must con- 
form to operating system standards. See the RMS-1l1 User's Guide, 
Appendix A, for RMS-11 restrictions on the operating systems and 
operating system restrictions on RMS-1ll. 


On RSTS/E, RMS-11 parses file specifications in the following se- 
quence. RMS-11: 


1. Places the string described by the DNA and DNS fields in the 
FIRQB. 


2. Issues a .FSS call on the string described by the FNA and _ FNS 
fields. In the process, the monitor merges the FNA and DNA 
strings in the FIRQB, overriding only those components already 
existing in the FNA string. The monitor also translates logi- 
cal names. 


3. Checks if the FSS processing encountered an RMS-11 restriction 
on RSTS/E file specifications, such as switches or an equal 
sign (=). 


4. Examines the resultant file specification for device and ac- 
count components. If these components are missing, RMS-11l ob- 
tains the system defaults for those fields and puts them _ into 
the file specification. 


5. Examines the resultant file specification. If a component is 
missing, returns the appropriate error code; if there are too 
many components, returns the error code ERSXTR. 
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3.15 FNS 


The one-byte File Name String Size (FNS) field contains the size, in 
bytes, of the file specification indicated by the FNA field. 


3.15.1 Use 


Input to: 
SCREATE/SOPEN 
If the FNA field is zero, RMS-1ll ignores the FNA field; if 
FNA is not zero, that is, you are providing a file specifi- 


cation, you should set the FNA field equal to the size of 
that string in bytes. 


3.15.2 Input Values 
The FNA field must contain either: 
e any value* if FNA is zero 


e size of the file specification string, in bytes, with a maximum of 
255 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


3.15.3 Initialization and Default 
Macro takes the form: 
FSFNS numeric 


If there is no initialization macro, FNS = 0. 


*Recommended value is the default, zero. 
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3.16 FOP 


The one-word File Processing Options (FOP) field contains a bit string 
indicating the file processing options that you have selected for the 
file represented by the FAB. 


3.16.1 Use 


Input to: 


SCREATE 
You set the FOP field to indicate the processing option(s) 
you want applied to the new file until it is closed. 


SOPEN 
You set the FOP field to indicate the processing options you 
want applied to the existing file until it is closed. 


SEXTEND 
You set the FOP field equal to FBSCTG if you want the file 
extended contiguously, that is, the new blocks allocated in 
such a manner that they are contiguous with the present ex- 
tent of the file. 


SCLOSE 
You set the FOP field equal to FBSRWC if you want a magnetic 
tape file rewound when the file is closed, but did not in- 
clude the option when the file was opened. 


Output from: 


SOPEN 
If the file is contiguous, RMS-11 sets the FOP field equal 
to FBSCTG; otherwise, the field is zero. You can test for 
this value with field access macros (See Chapter 7). 


3.16.2 Input Values 


The FOP field may contain one or more of the following symbolic 
values: 


FBSCTG RMS-11 is to allocate contiguously the amount of space 


specified in the FAB ALQ field. Used on SCREATE and 
SEXTEND only. 
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FBS DFW 


FBSDLK 


FBSFID 


FBSMKD 


FBSNEF 


FBSPOS 


FBSRWC 


FBSRWO 


FBSSUP 


directs RMS-11 to defer writing the I/O buffer out to a 
file after a SDELETE, SUPDATE, or SPUT operation. Under 
default conditions, RMS-11 causes a physical transfer of 
data from your program to the file as part of any of the 
above record operations-~-for Relative and Indexed files 
only. However, if you specify FBSDFW in the RAB when you 
initiate one of these operations, RMS-11 does not auto- 
matically write out the buffer. Instead, it defers the 
disk write until it requires the buffer for some other 
purpose, such as reading a different bucket into memory 
or the buffer is full. Since this is similar to the de- 
fault condition for Sequential files, specifying Deferred 
Write does not affect record operations on Sequential 
files. 


RMS-11 unlocks the file so that it is available for ac- 
cess if this program does not close it in a normal 
manner. Used on  SCREATE and SOPEN- only. See 
"Comments." 


RMS-11 uses the value in the NAM FID field to open or 


erase the file (see Chapter 8). Used on SOPEN and SERASE 
only. 


RMS-11 creates this file, then deletes it when the file 
is closed. Used on SCREATE only. 


RMS-11 does not position the ANSI magnetic tape to the 
end of the file even though the FAB FAC field contains 
FBSPUT. Used on SOPEN only. 


RMS-11 positions the magtape to the point immediately 
after the most recently closed file before it creates the 
file specified by this FAB; all subsequent files on the 
tape are logically deleted. If FBSPOS is not specified, 
RMS-11 positions the magtape at the end of the last file 
on the volume. However, the FBSRWO option overrides the 
FBSPOS option. Used on SCREATE only. 


RMS-11 requests the operating system to rewind the mag- 
tape when the file is closed. If FBSRWC is set when the 
file is opened (S$CREATE or SOPEN), RMS-11 does not notice 
its absence when the file is closed; that is, you can't 
undo this once specified. However, if FBSRWC was not 
specified for the open, you can include it for the S$CLOSE 
and RMS-11 rewinds the tape. 


RMS-11 requests the operating system to rewind the mag- 
tape before the file represented by the FAB is created 
and/or opened. Used on SCREATE and SOPEN only. 


RMS-11 supersedes an existing file if the file specifi- 


cation indicated by this FAB contains an explicit version 
number. Used on SCREATE only. 
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FBSTMD RMS-11 creates this file as a temporary file and deletes 
it when the file is closed. Used on S$CREATE only. 


FBSTMP RMS-11 creates this file as a temporary file and does not 
delete it; that is, RMS-11 retains the file, when it is 
closed, even though it is not entered into the directory. 
The FBSTMD option overrides the FBSTMP option. Used on 
SCREATE only. 


If you want to specify more than one option, you must concatenate’ the 
values using an exclamation point (!). 


A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (See Chapter 7). 


3.16.3 Initialization and Default 
Macro takes the form: 
FSFOP symbolic[!symbolic...] 
If there is no initialization macro, FOP = 0, meaning: 
e The file is created or extended noncontiguously. 
e If file is not closed normally, it remains locked (see "Comments"). 
e Open operation accesses file via filespec. 
e RMS-11 positions magtape to end of the file when it opens the file. 


e RMS-11 positions magtape to end of the last file on volume before 
it creates the specified file. 


e RMS-11 does not request the operating system to rewind magtape when 
the file is closed. 


e RMS-11 fails with error code ERSFEX if the filespec contains an 
explicit version number and the file already exists. 


e RMS-11 creates a permanent file. 


3.16.4 Comments 


e The IAS and RSX-11M operating systems provide protection to any 
file that is not closed properly* by a task that creates or opens 
it: the file is locked and not accessible by any user task until a 
utility (PIP) unlocks it. 


This protection is particularly valuable for Sequential files. 
When RMS-1l opens a Sequential file, it reads the file's attri- 
butes, including end-of-file location from the file header into 
memory; however, RMS-11 does not update the file header until the 
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file is closed. Until the file's attributes are revised on disk, 
any extension of the file while it was opened (and any data added 
to it) is not permanently recorded. Therefore, if a Sequential 
file is not closed properly*, all data added while it was open 
could be lost if another task does access the file and make its own 
revision of the file header. 


These considerations do not apply to Relative and Indexed files. 
Therefore, they are the only files for which the FBSDLK value 
should be specified, 


e Since the FOP field is a bit string, values cannot be added to the 
field with the S$STORE field access macro. You should use the SSET 
field access macro (see Chapter 7). However, you use the SSTORE 
Macro to (re)set all bits in the field. 


*Caused by an improperly designed task, operating system collapse, or 
hardware malfunction. 
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3.17 FSZ 
The one-byte Fixed Control Area Size (FSZ) field contains the size, in 


bytes, of the fixed control area for Variable-with-Fixed-Control (VFC) 
records in the file represented by the FAB. 


3.17.1 Use 


The FSZ field is only used when a file contains (or will contain) VFC 
records. It therefore applies only to Sequential and Relative files. 


Input to: 
SCREATE 
You set the FSZ field equal to the number of bytes in the 
fixed control area of the VFC records that will be written 
into the file to be created. 
Output from: 
SOPEN 


RMS-11 sets the FSZ field to the size of the fixed control 
area established when the file was created. 


3.17.2 Input Values 


MINIMUM = 0, meaning that RMS-11 sets the control area size to _ two 
bytes* 


1, the smallest fixed control area allowed 


MAXIMUM 255 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (See Chapter 7). 


3.17.3 Initialization and Default 
Macro takes the form: 
FSFSZ numeric 


*Compatible with FCS. 
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If there is no initialization macro, FSZ = 0. 


3.17.4 Comments 


RMS-11 uses this number as the size of the buffer indicated by the RAB 
RHB field. 
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3.18 IFI 
The SOPEN macro sets the one-word Internal File Identifier (IFI) field 


to an address that links the FAB to the IFAB RMS-11 creates when a 
file is opened. The SCLOSE macro clears the IFI field. 


CAUTION 


DO NOT CHANGE THE IFI FIELD. 


3.18.1 Use 


RMS-11 uses the address in the IFI field to transfer pertinent data 
from the FAB to the IFAB. 
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The one-byte Logical Channel (LCH) field contains the number of the 
logical channel through which all I/O operations between the file and 


the task are performed. 


3.19.1 Use 


Input to: 


SCREATE/SOPEN 


You set the LCH field to the number of the channel the file 
should be linked with until it is closed. Each file opened 
must have a unique LCH (error code ERSLBY). 


3.19.2 Input Values 


MINIMUM is system-dependent 


MAXIMUM is system-dependent 


A value can be set in the field with the 


initialization macro shown 


below or with the S$STORE field access macro (see Chapter 7). 


3.19.3 Initialization and Default 


Macro takes the form: 


FSLCH numeric 


If there is no initialization macro, 
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rau 


meaning the field must 
be set with the $STORE 
field access macro be- 
fore the file open is 
attempted. 


3.19.4 Comments 


Multiple Record Access Streams is a method of using one logical 
channel to carry multiple functions. 


Once a logical channel is assigned to a device, no operation, in- 


cluding S$CLOSE, automatically deassigns the channel. The channel 
remains assigned to the device until you reassign it. 
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3.20 MRN 


The two-word Maximum Record Number (MRN) field contains the maximu 
number of records that can be written to the Relative file associate 
with the FAB. RMS-11 checks the relative record number used with eac 
put operation against this maximum and rejects (error code ERSMRN) an 
operation with too high a number. 


3.20.1 Use 


The MRN field is only meaningful for Relative files. 


Input to: 


SCREATE 
You set the MRN field to the highest relative number of any 
record that will (or should) be written into the file*. If 


you want no checks on relative record number, set MRN equal 
to zero. 


Output from: 


SOPEN 


RMS-11 sets the MRN field equal to the value established 
when the file* was created. 


3.20.2 Input Values 


MINIMUM = 0, meaning that RMS-11 writes the MRN value as 
2,147,483,647** during the create operation, returns 
this number during an open operation, and makes no 
checks on relative record numbers during put opera- 
tions. 


MAXIMUM = number of records that will fit on the device containing 
the file 


*Unless the FAB ORG field contains FBSREL, RMS-11 ignores the MRN 
field during $CREATE and sets it to zero during SOPEN. 
**The largest possible positive value for the 32-bit field. 
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A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


3.20.3 Initialization and Default 
Macro takes the form: 
FSMRN numeric 


If there is no initialization macro, MRN = 0. 
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3.21 MRS 


The one-word Maximum Record Size (MRS) field contains the maximur 
size, in bytes, of any record in the file associated with the FAB. 
RMS-11 checks all records written to the file against this maximum and 
rejects those that are too large (error code ERSRSZ). 


3.21.1 Use 


Input to: 


SCREATE 
You set the MRS field equal to the number of bytes in: 


e all fixed-length records in the file 


e the largest variable-length or stream record that can be 
written to the file. 


e The variable area in the largest VFC record that can be 
written to the file, that is, the number does not include 
the fixed control area. 


Output from: 
SOPEN 


RMS-11 sets the MRS field equal to the value established 
when the file was created. 


3.21.2 Input Values 


MINIMUM 0, meaning that RMS-11 makes no checks on the length of re- 
cords written to the file via either $PUT or SUPDATE. 
However, there are restrictions on the use of zero in the 


MRS field; see "Comments." 


MAXIMUM = 32767, the largest number that can be stored in the _ signed 
two-byte field. However, Maximum Record Size is 
further limited by bucket size in Relative and In- 
dexed files and by task buffer space for all files. 


A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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3.21.3 Initialization and Default 
Macro takes the form: 
FSMRS numeric 


If there is no initialization macro, MRS = 0. 


3.21.4 Comments 


A nonzero MRS field is required during the S$CREATE operation in the 
following situations: 


e Fixed-length records (FAB RFM field = RBSFIX) 


® Relative file organization (FAB ORG field = FBSREL) 
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3.22 NAM 


The one-word Name Block Address (NAM) field points to a separately al- 
located Name Control Block (NAM) and thereby activates RMS-1l to use 
the NAM Block when the file is opened. See Chapter 6. 


3.22.1 Use 


Input to: 


SCLOSE 
If you have specified a valid NAM Block, RMS-1l clears’ the 
first word of the FID field, making the field invalid for 
any subsequent operations. 


SCREATE 


e If you have allocated a NAM Block and want RMS-11 to set 
the fields when it opens the file, you set the NAM field 
equal to the address of the block. 


e If you have not allocated a NAM Block and/or you do not 
want RMS-11 to fill it in during the file open procedure, 
set the NAM field equal to zero; otherwise, RMS-1l in- 
terprets the value in the field as an address and tries 
to use the area indicated as a NAM Block: if that area 
is not a valid NAM Block, RMS-11 returns the error code 
ERSNAM. 


SERASE 


e If you want RMS-11 to use the device and file IDs in NAM 
DVI and FID fields to identify, then erase a file. The 
file ID must be valid and probably was supplied by RMS-11 
during a create or open operation. You must also set 
FBSFID in the FAB FOP field. 


e If you have not allocated a NAM Block and/or you do not 
want RMS-1l to use it in during the erase operation, set 
the NAM field equal to zero; otherwise, RMS-11 inter- 
prets the value in the field as an address and tries to 
use the area indicated as a NAM Block: if that area is 
not a valid NAM Block, RMS-11 returns the error code 
ERSNAM. 
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SOPEN 


3.22.2 Input 
The NAM field 


e zero (0) = 


If you have allocated a NAM Block and want RMS-11 to fill 
in the fields when it opens the file, you set the NAM 
field equal to the address of the block. 


If you want RMS-11 to use the device and file IDs in NAM 
DVI and FID fields to identify, then open a file. The 
file ID must be valid and probably was supplied by RMS-11 
during a create or open operation. You must also set 
FBSFID in the FAB FOP field. 


If you have not allocated a NAM Block and/or you do not 
want RMS-11 to fill it in during the open operation, set 
the NAM field equal to zero; otherwise, RMS-1ll inter- 
prets the value in the field as an address and tries to 
use the area indicated as a NAM Block: if that area is 
not a valid NAM Block, RMS-11l returns the error code 
ERSNAM. 


Values 
must contain either: 


there is no NAM Block associated with this FAB 


e address of a Name Control Block separately allocated in the program 


A value can b 
below or with 


3.22.3 Initi 
Macro takes t 
FSNAM la 


If there isn 


e set in the field with the initialization macro shown 
the SSTORE field access macro (see Chapter 7). 


alization and Default 
he form: 
bel 


o initialization macro, NAM = 0. 
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3.23 ORG 


The one-byte File Organization (ORG) field contains an indicator for 
the organization of the file associated with the FAB. 


3.23.1 Use 


Input to: 
SCREATE 
You set the ORG field to indicate the organization you want 
established for the file to be created. 
Output from: 
SOPEN 
RMS-11 stores in the ORG field the indicator for the organi- 


zation of the existing file. You can test this value with 
field access macros (see Chapter 7). 


3.23.2 Input Values 

The ORG field may contain one of the following symbolic values: 
FBSSEQ Sequential file organization 
FBSREL Relative file organization 
FBSIDX Indexed file organization 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


3.23.3 Initialization and Default 
Macro takes the form: 
FSORG symbolic 


If there is no initialization macro, ORG = FBSSEQ. 
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3.24 RAT 


The one-byte Record Attributes (RAT) field contains a bit string des- 
cribing the attributes of the records in the file associated with the 
FAB. 


3.24.1 Use 


Input to: 


SCREATE 
You set the RAT field to indicate the characteristics of the 
records that will be stored in the file to be created. 


Output from: 


SOPEN 
RMS-11 stores in the RAT field indicators of the record at- 
tributes established for the file when it was created. You 
can test for these values using field access macros’ (see 
Chapter 7). 


3.24.2 Input Values 


The RAT field may contain one or more of the following symbolic 
values: 


FBSBLK records in the file do not cross block boundaries; valid 
only for Sequential files. This attribute restricts re- 
cord size to 512 bytes. 


FBSCR when RMS-11 writes a record from this file to a unit re- 
cord device, that is, a terminal or printer opened as a 
Sequential file, it precedes the record with a line feed 
character and follows it with a carriage return char- 
acter. RMS-ll may or may not actually add the char- 
acters, depending on the operating system, 


FBSFTN the first byte of each record in the file contains a FOR- 
TRAN forms control character 


If you want to specify more than one attribute, you must concatenate 
the values using an exclamation point (!). 
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A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 


3.24.3 Initialization and Default 


Macro takes the form: 


FSRAT symbolic[!symbolic...] 


If there is no initialization macro, RAT = 0, meaning: 


Records span block boundaries 


No carriage or FORTRAN control 


3.24.4 Comments 


If the file associated with the FAB is a unit record device, such 
as a terminal or printer, you should put at least FBSCR in the RAT 
field. 


By default, records in all files are allowed to cross block boun- 
daries. Although this attribute can be restricted for Sequential 
files, there seems to be little reason to do So. 


Since the RAT field is a bit string, values cannot be added to’ the 
field with the SSTORE field access macro. You should use the SSET 
field access macro (see Chapter 7). However, you use the SSTORE 
Macro to (re)set all bits in the field. 
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3.25 REM 


The one-byte Record Format (RFM) field contains an indicator for the 
format of the records in the file associated with the FAB. 


3.25.1 Use 


Input to: 
SCREATE 
You set the RFM field to indicate the record format you want 
established for the file to be created. 
Output from: 
SOPEN 
RMS-11 stores in the RFM field the indicator for the record 


format of the existing file. You can test this value with 
field access macros (see Chapter 7). 


3.25.2 Input Values 
The RFM field may contain one of the following symbolic values: 

FBSFIX fixed-length records 

FBSSTM ASCII stream record format; valid only for disk Sequen- 
tial files. The RMS-11 User's Guide explains how RMS-11 
handles stream records. 

FBSUDF no record format is defined for the file; valid only for 
Sequential files during create operations. When access- 
ing a file with undefined record format, your program 
must use block I/O (see Chapter 9). 

FBSVAR variable-length records 


FBSVFC variable-with-fixed-control records; valid only for disk 
Sequential and Relative files 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 
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3.25.3 Initialization and Default 
Macro takes the form: 
FSRFM symbolic 


If there is no initialization macro, RFM = FBSVAR. 
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The meaning of the RTV field depends on your operating system. This 
section defines the field for: 


IAS/RSX-11M 


3.26 RTV 

The one-byte Retrieval Window Size (RTV) field contains the number of 
retrieval pointers kept in memory* for the file represented by the 
FAB. Retrieval pointers map virtual block numbers tto logical block 


numbers. See Chapter 8 of the RMS-11 User's Guide for more informa- 
tion. 


3.26.1 Use 
Input to: 
SCREATE/SOPEN 


You set the RTV field equal to the size of window you want 
maintained for the file until it is closed. 


3.26.2 Input Values 
The RTV field must contain one of the following: 
e -l = as much of the file as possible is mapped with one window 


e O 


RMS-11 uses the current default value 


@e a nonzero positive value, specifying the number of retrieval  po- 
inters to be maintained in memory: 


MINIMUM 
MAXIMUM 


1 
127 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


*This set of pointers is called a "window." 
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3.26.3 Initialization and Default 
Macro takes the form: 
FSRTV numeric 


Tf there is no initialization macro, RTV = 0. 
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The meaning of the RTV field depends on your operating system. This 
section defines the field for: 


RSTS/E 


3.27 RTV 


The one-byte Clustersize (RTV) field contains the number of blocks in 
each cluster of the file represented by the FAB. 


3.27.1 Use 
Input to: 
SCREATE 
You set the RTV field to the clustersize you want esta- 
blished for the file to be created. 
Output from: 
SOPEN 


RMS-11 sets the RTV field to the clustersize established for 
the file when it was created. 


3.27.2 Input Values 

The value in the RTV field must be: 

@® a positive integer 

@e a power of two; else ERSCRE 

e greater than or equal to volume* clustersize 


MINIMUM 


0, meaning that RMS-11 uses the volume* clustersize 


MAXIMUM 


255, meaning that RMS-11 sets clustersize to 256 blocks 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


*"Volume" means the disk pack as opposed to the disk device, which has 
its own characteristic clustersize. 
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3.27.3 Initialization and Default 
Macro takes the form: 
FSRTV numeric 


If there is no initialization macro, RTV = 0. 
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3.28 SHR 


The one-byte File Sharing (SHR) field contains a bit string indicating 
the operations on the file represented by the FAB you are willing to 
share with other tasks. This sharing criterion is applied whether or 
not this is the first task to access the file: if one or more other 
tasks have already opened the file to write and the SHR field _ indi- 
cates no write sharing, the open operation fails; however, if this 
task is the first to open the file, specifying no write sharing, all 
other tasks that indicate write operations* are denied access. 


See also Chapter 2 of the RMS-11 User's Guide. 


3.28.1 Use 
Input to: 
SCREATE/SOPEN 


You set the SHR field to indicate the type of operations you 
allow other tasks accessing the file. 


3.28.2 Input Values 
The SHR field may contain one of the following: 


e zero (0), meaning no write sharing; however, other tasks may ac- 
cess the file for reading only (FBSGET only in the FAB ROP field) 


e FBSWRI, meaning that other tasks may access the file for write op- 
erations 
NOTE 
For Sequential files, FBSWRI can be used only when the FAC 


field does NOT contain FBSPUT or FBSUPD. If you want write 
access, you cannot allow others to have write access. 


A value can be set in the field with the initialization macro shown 


*FBSDEL, FBSPUT, and/or FBSUPD in FAB ROP field. 
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below or with the SSET field access macro (See Chapter 7). 


3.28.3 Initialization and Default 
Macro takes the form: 
FSSHR FBSWRI 


If there is no initialization macro, SHR = 0. 
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3.29 STS 


The one-word Completion Status Code (STS) field contains a code indi- 
cating the success or failure (and type of failure) of a file opera- 
tion. See Appendix A for symbolic and octal codes for both success 
and failure of operations. 


3.29.1 Use 
Output from: 
SC LOSE/SCREATE/SDIS PLAY/SERASE/SEXTEND/SOPEN 
RMS-11 sets the STS field equal to a completion code. You 
should test this field ($COMPARE field access macro) for a 
negative value after each file operation, or you can use an 


error completion routine that checks the value (see Chapter 
8). 


3.29.2 Input Values 


No input values; see Appendix A for output values. 
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The one-word Status Value (STV) field contains additional information 
about some error codes returned in the STS field. 


3.30.1 


Use 


Output from: 


$C LOSE/SCREATE/S$DIS PLAY/SERASE/SEXTEND/S$OPEN 


3.30.2 


RMS-11 sets the STV field whenever it has additional  infor- 
mation to communicate about an error. See Appendix A for 
the specific errors on which the STV field is used. You 
should check the STV field for a nonzero value whenever you 
detect an error (negative value in STS field). 


Input Values 


No input values; see Appendix A for output values. 
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3.31 XAB 

The one-word Extended Attribute Block Address (XAB) field, if not 
zero, points to a separately allocated Extended Attribute Block (XAB) 
and thereby indicates to RMS-11 that there is a chain of at least one 
XAB that must be examined for input to and filled with output from a 


file operation. RMS-11 finds the other XABs in the chain, if there 
are any, via the NXT field in the XAB indicated by the FAB XAB field. 


3.31.1 Use 
Input to: 
SCREATE/SDISPLAY/SEXTEND/SOPEN 
e If you have allocated one or more XABsS and want RMS-11 to 
use the chain, you set the XAB field equal to the address 
of the first XAB in the chain. 
e If you have not allocated an XAB and/or you do not want 
RMS-11 to use it during the file open procedure, set the 
XAB field equal to zero; otherwise, RMS-11 interprets 
the value in the field as an address and tries to use the 


area indicated as an XAB: if that area is not aevalid 
XAB, RMS-1ll returns error code ERSXAB. 


3.31.2 Input Values 
The XAB field must contain either: 
e zero (0) = there is no XAB associated with this FAB 


e address of an Extended Attribute Block separately allocated in the 
program 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


3.31.3 Initialization and Default 
Macro takes the form: 


FSXAB label 
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If there is no initialization macro, XAB = 0. 


3.31.4 Comments 
e See Chapter 5 for details on XABs. 


e An Indexed file requires at least one XAB to define the Primary 
Key. 
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CHAPTER 4 


RECORD ACCESS BLOCK 


The initialization macros (this chapter) and the field access macros 
(Chapter 7) are provided so that you do not have to know the specific 
position and to a large extent, the size of each field in a RAB. You 
can, therefore, treat the fields as logical entities. It is also pos- 
sible that the positions and sizes of the fields will change from re- 
lease to release of RMS-1l. 


However, you can determine the position of any field in a RAB as an 
offset from the RAB's starting address. RMS-11 represents these off- 
set values with symbols in one of the following forms: 


e oOStnm 
where fnm is the three-letter name of a one-byte or one-word field; 
fnm is the name used to reference the field in the initialization 
and field access macros. 
Example OSSTS for the status code field 


e oOSfnmx 


where fnm is the name of a multiword field; fnm is the name used 
to reference the field in the initialization and field 
access macros. 


x is a number associated with an individual word in the 
field, from 0 through the end of the field. 


Example OSBKTO for less significant word and QSBKT1 for the more 
Significant word in the BRKT field 


The values of these symbols can be found in the symbol table of an as- 
sembly listing file for any module containing the RAB. 


Table 4-1: Record Access Block Fields 


Field Field Default Description 
Name Size 


N/A RAB identifier 
Relative record number or VBN 
RAB length 

User area 

FAB address 

Pointer to IRAB 

Key buffer address 

Key of reference 

Key buffer size 

Multiblock count 

Multibuffer count 

Record Access Mode 

Address of output record 
Record's File Address 

Fixed control area buffer 
Record processing options 
Size of output record 
Completion status code 
Status value 

Input record buffer 
Input record buffer size 
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4.1 BID 


The RABSB macro sets the one-byte Block Identifier (BID) field to’ the 
Record Access Block identifier, with the symbolic value of RBSBID. 


CAUTION 


DO NOT CHANGE THE BID FIELD. 


4.1.1 Use 


Before RMS-11 uses a RAB during a record operation, it verifies that 
the block is a valid RAB; one of the checks examines the BID field. 
If this field does not contain the proper code, RMS-11 terminates’ the 
operation with a ERSRAB error code. 
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4.2 BRKT 
The one-byte Bucket (BKT) field contains: 


e the relative record number of the record accessed by the Record Ac- 
cess Stream during sequential access operations on a Relative file 


e the Virtual Block Number when the Record Access Stream is’ perform- 
ing Block I/O operations 


4.2.1 Use 


Input to Block I/O Operations: 
SREAD/SWRITE 
You set the BKT field equal to the number of the virtual 
block you want read or written. 
Output from Relative File record operations: 
SFIND/SGET/S$PUT 
If you have specified sequential access (RBSSEQ in the RAB 
RAC field), RMS-1l1 sets the BKT field equal to the relative 


record number of the record read or written by the opera- 
tion. 


4.2.2 Input Values (Block I/O only) 
MINIMUM = 0 
MAXIMUM = value of FAB ALQ field 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


4.2.3 Initialization and Default 
Logical for Block I/O operations only, the macro takes the form: 
RSBKT numeric 


If there is no initialization macro, BKT = 0. 


4-4 Record Access Block (RAB): BKT 


KREKKRKKKKKKKKE 


x * 
* BLN * 
* * 
KRKKEKKKKEEEKE 


4.3 BLN 


The RABSB macro sets the one-byte Block Length (BLN) field to the Re- 
cord Access Block length, with one of the following symbolic values: 


RBSBLN synchronous RAB 


RBSBLL = asynchronous RAB 


CAUTION 


DO NOT CHANGE THE BLN FIELD. 


4.3.1 Use 


Before RMS-11 uses a RAB during a record operation, it verifies that 
the blocks is a valid RAB; one of the checks examines the BLN field. 
If this field does not contain the proper code, RMS-11 aborts the op- 
eration with a ERSBLN error code. 
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4.4 CTX 
The one-word User Context (CTX) field is not used by RMS-11, but is 


made available to you to contain any information you want associated 
with the Record Access Stream during run time. 


4.4.1 Use 


Anything you want. For example, you might use the CTX field to com- 
municate with a common completion routine. 


4.4.2 Input Values 
Anything you want, as long as it fits in 16 bits. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


4.4.3 Initialization and Default 
Macro takes the form: 

RSCTX argument 
where argument is any value you want. 


If there is no initialization macro, CTX = 0. 
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4.5 FAB 


The one-word File Access Block (FAB) field points to the File Access 
Block connected to this RAB to form a Record Access Stream (RAS). The 
FAB must be associated with an open file at the time the SCONNECT 
macro is used. If an invalid address is stored in the FAB field, 
RMS-11 returns error code ERSIFI. 


4.5.1 Use 


Input to: 


SCONNECT 
You set the FAB field equal to the address of the FAB you 
want associated with this RAB to make a Record Access Stre- 
am. 


4.5.2 Input Values 


Before the $CONNECT macro is executed, you must put a valid FAB ad- 
dress in the FAB field. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


4.5.3 Initialization and Default 
Macro takes the form: 
RSFAB label 
If there is no initialization macro, FAB = 0, meaning you must set the 
field with the SSTORE 
field access macro be- 


fore initiating 
SCONNECT. 
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4.5.4 Comments 


If you are using the same FAB for more than one file, you should set 
up all Record Access Streams associated with one file before you modi- 
fy the FAB in preparation for another SOPEN or SCREATE. 
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4.6 ISI 


The SCONNECT macro sets the one-word Internal Stream Identifier (ISI) 
field to an address that links the RAB to the IRAB RMS-11 has created. 


CAUTION 


DO NOT CHANGE THE ISI FIELD. 


4.6.1 Use 


RMS-11 uses the address in the ISI field to transfer pertinent data 
from the RAB to the IRAB. 
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4.7 KBF 


The one-word Key Buffer (KBF) field points to the key that RMS-11 uses 
to locate a record during a random record operation: 


e For Relative files, RMS-1l uses the value as the relative record 
number for $FIND, SGET, and SPUT operations. 


e For Indexed files, RMS-1l uses the buffer contents as the key value 
during its index search for $FIND and SGET operations. The RAB KRF 
field determines the specific index searched and the contents of 
the RAB KSZ and ROP fields decide the match criteria used. 


4.7.1 Use 


Input to: 


SFIND/SGET 
You set the KBF field to the address of the buffer in your 
program that contains the key for the next random record op- 
eration (RBSKEY in RAB RAC field). You must also set the 
KSZ and ROP fields appropriately. 


SPUT 
For Relative files, you set the KBF field to indicate the 
relative record number of the cell where RMS-11 should write 
the specified record. 


4.7.2 Input Values 


The KBF field must contain a valid address before any random record 
operation macro is executed. 


The address must indicate a buffer in the current program that con- 
tains either: 


@ a relative record number as a two-word integer that is positive, at 
least 1, and no greater than the Maxium Record Number (MRN) set for 
the file when it was created. The address must point to the least 
significant byte of the record number. 


e a key value for an index search; this value can be any of the 
valid Indexed key types. 


4-10 Record Access Block (RAB): KBF 


The buffer does not have to be word-aligned. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


4.7.3 Initialization and Default 
Macro takes the form: 
RSKBF label 


If there is no initialization macro, KBF = 0, meaning you must set the 
field with the SSTORE 
field access macro be- 
fore any random record 
operation. 
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4.8 KRF 


The one-byte Key of Reference (KRF) field indicates the index to be 
referenced in the current operation. 


4.8.1 Use 
The KRF field is only used for record operations on Indexed files. 
Input to: 


SFIND/SGET 
You set the KRF field to indicate the index that should be 
searched for the value defined by the contents of the KBF 
and KSZ fields; match criterion is also specified by the 
ROP field. 


SCONNECT/SREWIND 
You set the KRF field to indicate the index that is used to 
set the context of the Record Access Stream, that is, the 
logical first record in the file. 


4.8.2 Input Values 


MINIMUM 0, meaning the Primary Key 


MAXIMUM 


254 


All values beginning with 1 indicate Alternate Keys, first, second, 
and so on. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (See Chapter 7). 


4.8.3 Initialization and Default 
Macro takes the form: 
RSKRF numeric 


If there is no initialization macro, KRF = 0. 
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4.9 KSZ 


The one-byte Key Size (KSZ) field contains the size, in bytes, of the 
key buffer indicated by the KBF field. RMS-1l1l requires specific sizes 
for a relative record number and all Indexed key types except string 
(see "Values"). However, for string keys, RMS-11 uses the number of 
characters specified in KSZ as a length criterion in the index search 
required by the record operation. Therefore, before a search can be 
successful, RMS-11 must find a record with a key value that matches 
the value indicated by KBF to the number of characters indicated by 
KSZ. If KSZ equals the length of the key (established when the file 
was created), the search requires an exact match, whereas when KSZ is 
less than the key length, only an approximate match is needed. 


The value of the ROP field also affects match criteria. 


4.9.1 Use 


Input to: 
SFIND/SGET 
For Relative files, you must set the KSZ field equal to 0 or 
4. 
For Indexed files, you set the KSZ field equal to: 


e specific number of bytes for all key types except string 


e the number of characters in a key field that must match 
the KBF value before the search is successful 


SPUT 


For Relative files, you must set the KSZ field equal to 0 or 
4. 


4.9.2 Input Values 


The values of the KSZ field depend on the type of key indicated by the 
KBF field: 


e Relative Record Number (FBSREL in FAB ORG field), KSZ = 4 (0 de- 
faults to 4) 


Record Access Block (RAB): KSZ 4-13 


e String Key Type (FBSIDX in FAB ORG field): 


MINIMUM 


1 


MAXIMUM = size of key indicated by the KRF field 
e 15-bit Signed Integer Key Type, KSZ = 2 (0 defaults to 2) 
e 31-bit Signed Integer Key Type, KSZ = 4 (0 defaults to 4) 


e 16-bit Unsigned Binary Key Type, KSZ 


2 (0 defaults to 2) 


" 


e 32-bit Unsigned Binary Key Type, KSZ 4 (0 defaults to 4) 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (See Chapter 7). 


4.9.3 Initialization and Default 
Macro takes the form: 
RSKSZ numeric 
If there is no initialization macro, KSZ = 0, meaning you must set the 
field with the SSTORE 
field access macro be- 


fore any Indexed random 
record operation. 


4.9.4 Comments 


RMS-11 uses the KSZ field only for Indexed random record operations 
with string keys. 
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4.10 MBC 


The one-byte Multi-Block Count (MBC) field contains number of blocks 
from a disk Sequential file that RMS-11 reads or writes as a single 
T/O unit while the Record Access Stream is set up (between S$CONNECT 
and SDISCONNECT). 


4.10.1 Use 


The MBC field should be set for disk Sequential files only; take the 
default of one for all other files. See also the RMS-1l User's Guide. 


Input to: 
SCONNECT 
You set the MBC field equal to the number of blocks you want 


read from or written to the file in each I/O access opera- 
tion. 


4.10.2 Input Values 


MINIMUM 0, meaning: one block is the I/0 unit 


MAXIMUM 


63. 


A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 


4.10.3 Initialization and Default 
Macro takes the form: 
RSMBC numeric 


If there is no initialization macro, MBC = 0. 


4.10.4 Comments 


e See the RMS-11 User's Guide for a discussion of the use of MBC in 
optimization. 
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® The value in the MBC field determines the size of the I/0 buffer 
used for the file represented by the FAB indicated by the RAB FAB 
field. See Chapters 1 and 2. 
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4.11 MBF 


The one-byte Multi-Buffer (MBF) field contains the number of buffers* 
RMS-11 allocates for I/O operations when the Record Access Stream is 
set up ($CONNECT). 


4.11.1 Use 


The MBF field should be set only for Indexed files, although RMS-11 
uses it for Relative files as well: take the default value of one for 
Relative files. 


Input to: 


SCONNECT 
If you want to cache index Root buckets, set the MBF field 
to a number greater than two to make buffers available (see 
"Values"). 


4.11.2 Input Values 


MINIMUM = 0, meaning RMS-11 allocates the minimum number of buffers 
required by the file organization. Sequential and Rela- 
tive files require one buffer; Indexed files require two 
buffers. 

MAXIMUM = 255 


A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (See Chapter 7). 


4.11.3 Initialization and Default 
Macro takes the form: 
RSMBF numeric 


If there is no initialization macro, MBF = 0. 


*A buffer is one bucket long. 
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4.11.4 Comments 


e The value in the MBF field affects the size of the buffer pool for 
the file. See Chapters 1 and 2. 


e Although RMS-11 does respond to the MBF field for non-Indexed 
files, the use of a value greater than the minimum (other than the 
default) is a waste of address space and the use of a macro to set 
the value. 


e See the RMS-11 User's Guide for a discussion of the use of MBF in 
optimization. 


e The value in the MBF field should incorporate the minimum require- 
ments for the Indexed file: add the number of Roots you want 
cached to the minimum requirements to get the value for the MBF 
field. 

e If the value is: 


-- less than minimum, RMS-11 allocates the minimum number of 
buffers 


-- more than two for Sequential files, RMS-11 allocates only two 
buffers 


-- more than is available, RMS-11 allocates as many buffers as pos- 
Sible 
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4.12 RAC 


The one-byte Record Access (RAC) field contains an indicator for the 
access method to be used in a record operation. 


4.12.1 Use 


Input to: 
SFIND/SGET/SPUT 


You set the RAC field to indicate the access method RMS-11l 
should use to locate the next record position. 


4.12.2 Input Values 
The RAC field must contain one of the following symbolic values: 
RMSKEY RMS-11 performs a random record operation, using specifi- 
cations from the KBF, KSZ, and if necessary KRF and ROP 
fields. Random access applies only to Relative and _ In- 
dexed files. 
RBSRFA RMS-11 performs a record operation using the Record's 
File Address specified in the RFA field to locate the re- 
cord position. RFA access applies only to disk files. 
RBSSEQ RMS-11 performs a sequential record operation. 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


4.12.3 Initialization and Default 
Macro takes the form: 
RSRAC symbolic 


If there is no initialization macro, RAC = RBSSEQ. 
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4.13 RBF 


The one-word Record Buffer (RBF) field points to the buffer in the 
program that contains the 
record moved by the record operation. 


4.13.1 Use 


Input to: 


SPUT/SUPDATE 
Regardless of the Record Transfer Mode, you must set the RBF 
field equal to the address of the first byte of the record 
you want written to the file. You must also set the RSZ 
field. 


Output from: 


SGET 
Regardless of Record Transfer Mode, RMS-11 sets the RBF 
field equal to the address of the first byte of the record 
read from the file. The RSZ field is also set. 

SPUT 


When your program is writing records to a Sequential file in 
the Locate Record Transfer Mode, RMS-11l returns an address 
in the RBF field after each $PUT operation. This address is 
the location where your program can build the next record. 
If your program uses this location, it must set the RSZ 
field to describe the record that begins at the location. 
However, if your program does not use the address, it must 
reset both the RBF and RSZ fields. 


4.13.2 Input Values 
The RBF field must contain a valid address. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 
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4.13.3 Initialization and Default 
Macro takes the form: 
RSRBF label 


If there is no initialization macro, RBF = 0, meaning you must set the 
field with SSTORE before 
a put or update opera- 
tion is initiated. 


4.13.4 Comments 


During the simplest of processes, that is, in Move Record Transfer 
Mode and the same records are being read and written/updated, the 
RBF/RSZ and UBF/USZ fields describe the same buffer within your pro- 
gram: 


e RBF/RSZ describe the record that RMS-11 moves out of your program 
to the file. 


e UBF/USZ describe the buffer where RMS-11 places each record read 
from the file. 


In anticipation of this common usage, RMS-1l resets RBF after a _suc- 
cessful get operation so that you don't have to set it before initiat- 
ing a SUPDATE macro: when RBF and UBF point to the same buffer, RBF 
is not changed. 
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4.14 RFA 
The three-word Record's File Address (RFA) field contains the file ad- 


dress of the target record for or from a get or find operation or of 
the record written by a put operation. 


4.14.1 Use 


Input to: 
SFIND/SGET 
If you have set the RAC field to RBSRFA, you set the RFA 
field equal to the Record's File Address of the record you 
want found or read. 
Output from: 
SFIND/SGET 
If the RAC field does not contain RBSRFA, RMS-1l1l sets_ the 


RFA field equal to the Record's File Address of the record 
found or read. 


SPUT/SUPDATE 


RMS-11 sets the RFA field equal to the Record's File Address 
where it wrote the record specified. 


4.14.2 Input Values 


If the RAC field contains RBSRFA, the RFA must contain a valid 
Record's File Address for the file; otherwise, error code ERSRFA. 


A value cah be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


4.14.3 Initialization and Default 
Macro takes the form: 
RSRFA numeric 


If there is no initialization macro, RFA = 0. 
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4.15 RHB 


The one-word Record Header Buffer (RHB) field points to the buffer in 
the program containing the fixed control area of 
Variable-with-Fixed-Control (VFC) records. When RMS-11l gets a record, 
it separates the fixed control area from the variable portion of the 
record; it places the fixed data in the buffer indicated by the RHB 
field and the variable data in the buffer indicated by the UBF field. 
For put operations, RMS-11l prefixes the data from the RHB buffer to 
the data in the RBF buffer before it moves the entire record from the 
program to the I/O buffer and then to the file. 


If no RHB buffer is indicated (the RHB field is zero), but the file 
contains VFC records (FBSVFC in the FAB RFM field), RMS-11 does the 
following: 


e ignores the fixed control area of records read ($GET) from the file 


e fills the fixed control area of records written (SPUT) to the file 
with zeros 


e does not change the fixed control area of records during update op- 
erations 


4.15.1 Use 


Input to: 


SGET/SPUT/SUPDATE 
e If you want the fixed control area of each record read 
and written properly, set the RHB field equal to the ad- 
dress of a buffer in the program. 


e If you do not want the fixed control area of each’ record 
read or written, ensure that the RHB field is zero; 
otherwise, RMS-1l interprets the value in the field as an 


address and tries to use the area indicated as a buffer: 
the results are unpredictable. 


4.15.2 Input Values 
The RHB field must contain either: 


e zero (0) = there is no buffer for the fixed control area 
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e address of the fixed control area buffer. This buffer must 
least as long as the value* in the FAB FSZ field indicates. 


A value can be set in the field with the initialization macro 
below or with the SSTORE field access macro (see Chapter 7). 


4.15.3 Initialization and Default 
Macro takes the form: 
RSRHB label 


If there is no initialization macro, RHB = 0. 


4.15.4 Comments 


be at 


shown 


During Locate Mode operations, the variable area data is accessed in 


the I/O buffer, but the data in the fixed control area is moved 
from the buffer described by the RAB RHB and FAB FSZ fields. 


me mee ce eee ee cer eee ee me ee ee ee ee ee ee ee 


*This value is a file attribute established when the file was 
and set in the FAB FSZ field by the file open process, 
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4.16 ROP 


The one-word Record Processing Options (ROP) field contains a bit 
string indicating optional functions that you want RMS-11 to perform 
while this Record Access Stream is set up (between S$CONNECT and 
SDISCONNECT). 


4.16.1 Use 


Input to: 


SCONNECT/SDELETE/SFIND/SGET/SPUT 
You set the ROP field to indicate the optional functions you 
want RMS-11l to perform. 


4.16.2 Input Values 


The ROP field may contain one or more of the following symbolic 
values: 


RBSASY RMS-11 performs an asynchronous record operation, possi- 
bly returning control to your program before the opera- 
tion is completed. The RAB must have been defined as as- 
ynchronous type by the RABS$B macro (see "Allocation" at 
the beginning of this chapter). 


RBSEOF RMS-11 sets the context of the stram at the end of the 
file when the SCONNECT macro is finished; valid for disk 
Sequential files only. This feature enables you to op- 
timize buffer space: when you are adding records to a 
Sequential file, you can: 


e disconnect the Record Access Stream when you are not 
using the file. This operation releases buffer space 
for use by other operations. 


e connect the Record Access Stream at end-of-file, ready 
to put another record. 


RBSFDL RMS-11 uses the Fast Delete procedure; valid for Indexed 
files only. During $DELETE execution, RMS-11 flags the 
user data record in the file as being deleted, but it up- 
dates Alternate indexes depending on whether duplicates 
are allowed: 


om 


RBSKGE 


RBSKGT 


RBSMAS 


DnannvaA 


e If duplicates are allowed, the SIDR array entry for 
the deleted record is NOT flagged as deleted. 
Thereafter, a find or get operation using that key 
value for that Alternate index will go to the Primary 
Level 0 bucket before it detects that the record has 
been deleted. 


e If duplicates are not allowed, the SIDR is_ removed 
from the Alternate Level 0 bucket. 


RMS-11's search during a find or get operation depends on 
file organization: 


e In Relative files, RMS-11l checks the cell specified by 
the relative record number in the RAB KBF field; if 
the cell contains a valid record, the search ends. 
However, if the cell is empty or contains a deleted 
record, RMS-11 continues searching sequentially 
through the cells until it finds a valid record, en- 
counters end-of-file, or exceeds the Maximum Record 
Number. 


e In Indexed files, RMS-11 searches for the first record 
containing a value in the key specified by the KRF 
field that is greater than or equal to the value des- 
cribed by the KBF and KSZ fields. 


RMS-11's search during a find or get operation depends on 
file organization: 


e In Relative files, RMS-1l1 starts at the cell with a 
relative record number one higher than the number in 
the RAB KBF field and searches sequentially through 
the cells until it finds a valid record, encounters 
end-of-file, or exceeds the Maximum Record Number. 


e In Indexed files, RMS-11 searches for the first record 
containing a value in the key specified by the KRF 
field that is greater than the value described by the 
KBF and KSZ fields. 


indicates to RMS-11 that you intend to insert a series of 
records at the logical end of an Indexed file. These re- 
cords must be sorted in ascending order by the Primary 
Key value, and the lowest Primary Key value in the ser- 
ies, that of the first record, must be higher than any 
Primary Key value already in the file. To implement Mass 
Insert, RMS-1l keeps the data bucket locked after the 
SPUT operation ends and maintains a pointer into the 
index bucket above the data bucket in the index. This 
effort enables RMS-11 to rapidly insert records into the 
file, splitting buckets economically if necessary. The 
presence of Alternate Keys degrades this performance. 
Activating Deferred Write (FBSDFW) enhances it. 
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RBSLOA RMS-11 obeys bucket fill numbers when it is inserting re- 
cords; valid for Indexed files only. See Allocation XAB 
DFL and IFL fields and the RMS-1ll User's Guide. 

RBSLOC RMS-11 uses the Locate Record Transfer Mode for get oper- 
ations on all file organizations and for put operations 
for Sequential files only. See the RMS-11 User's Guide. 

RBSUIF If RMS-11 encounters a record in the target cell during a 
put operation, it updates the record rather than return- 
ing error code ERSREX; valid for Relative files only. 


If you want to specify more than one option, you must concatenate the 
values using an exclamation point (!). 


A value can be set in the field with the initialization macro shown 
below or with the SSET field access macro (see Chapter 7). 
4.16.3 Initialization and Default 
Macro takes the form: 
RSROP symbolic[!symbolic...] 
If there is no initialization macro, ROP = 0, meaning: 
e Synchronous record operation 


e Context in a disk Sequential file after SCONNECT is the first re- 
cord in the file. 


e RMS-11 removes SIDR duplicate array entries from Alternate indexes 
during delete operations on Indexed files. 


e RMS-11 requires that a record's key value be equal to the value 
specified by the KBF and KSZ fields before it returns the record to 
the task. 

e RMS-11 completely fills Indexed file buckets. 


@ Move Record Transfer Mode 


e If RMS-11 encounters a record in the target cell during a put oper- 
ation on a Relative file, it returns error code ERSREX. 


4.16.4 Comments 


Since the ROP field is a bit string, values cannot be added to the 
field with the $STORE field access macro. You should use the SSET 
field access macro (see Chapter 7). However, you use the S$STORE macro 
to (re)set all bits in the field. 
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4.17 RSZ 


The one-word Record Size (RSZ) field contains the size, in bytes, of 
the record indicated by the RBF field. 


4.17.1 Use 


Input to: 
SPUT/SUPDATE 
You set the RSZ field equal to the size of the record in the 
record buffer indicated by the RBF field. RMS-11 moves only 
the number of bytes specified. 
Output from: 
SGET 


RMS-11 sets the RSZ field equal to the length of the’ record 
it placed in the buffer indicated by the UBF field. 


4.17.2 Input Values 
MINIMUM = 1 


MAXIMUM 


65535, but maximum record size is also affected by file 
structure, file organization, and task address space. 
See the RMS-1l1 User's Guide. 


A value of 0 is valid for only Sequential and Relative files with stre- 
am or variable-length records. 


A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 
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4.17.3 Initialization and Default 
Macro takes the form: 
RSRSZ numeric 


If there is no initialization macro, RSZ = 0, 


NOTE 


RSZ is also input to the S$UPDATE macro; 
operation must be preceded by a get (or 


tion sets the RSZ field so you don't have to set 
an update operation unless the record size changes. 


meaning you must set the 
field with the SSTORE 
field access macro be- 
fore a S$PUT operation* 
is initiated. 


however, an update 
find): that opera- 
it before 
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4.18 sTS 


The one-word Completion Status Code (STS) field contains a code indi- 
cating the success or failure (and type of failure) of the last record 
operation. See Appendix A for symbolic and octal codes for both suc- 
cess and failure of operations. 


4.18.1 Use 


Output from: 


SCONNECT/SDELETE/SDISCONNECT/SF IND/SGET/S$PUT/SUPDATE/SREWIND/ 
STRUNCATE/S$FLUSH/SNXTVOL 


RMS-11 sets the STS field equal to a completion status code. 
You should test this field (SCOMPARE field access macro) for 
a negative value after each record operation, or you can use 
an error routine that checks the value (see Chapter 8). 


4.18.2 Input Values 


No input values; see Appendix A for output values. 
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4.19 STV 


The one-word Status Value (STV) field contains additional information 
about some error codes returned in the STS field. 


4.19.1 Use 


Output from: 


SCONNECT/SDELETE/$DISCONNECT/SF IND/SGET/$PUT/SUPDATE/SREWIND/ 
STRUNCATE/$FLUSH/S$NXTVOL 
RMS-11 sets the STV field whenever it had additional infor- 
mation to communicate about an error. See Appendix A for 
the specific errors on which the STV field is used. You 
should check the STV field for a nonzero value whenever your 
program detects an error (negative value in STS field). 


4.19.2 Input Values 


No input values; see Appendix A for output values. 
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4.20 UBF 


The one-word User Buffer (UBF) field points to a buffer in your. pro- 
gram where RMS-1l1l should place a record read from the file or that 
RMS-11 can use during Locate Mode if necessary. 


4.20.1 Use 


Input to: 


SCONNECT 
RMS-11 transfers the address in the UBF field to the RBF 
field so that your program does not have to treat the first 
put in Locate Mode on a Sequential file as a special case. 


SGET 
Regardless of Record Transfer Mode (RTM), you set the UBF 
field equal to the address of the first byte of the record 
buffer you have provided for RMS-11 to store the record it 
reads from the file: 


e In Move RTM, RMS-11 automatically places the retrieved 
record in the buffer indicated by UBF. 


e In Locate RTM, RMS-11 normally leaves the retrieved re- 
cord in the stream's I/0 buffer and then sets the RBF 
field to its address. However, RMS-11 can determine that 
it cannot perform the record operation in Locate mode 
(see UG): it then moves the record into the buffer indi- 
cated by UBF. 


In either circumstance, if the buffer described by UBF is 
too small to contain the retrieved record, RMS-11 moves as 
much of the record as possible into the buffer (the number 
of bytes in the USZ field), updates the context of the stre- 
am, and returns error code ERSRTB 


SPUT 
During Locate Mode operations on Sequential files only, UBF 
must continue to point to a valid record buffer within your 
program. Normally after a put operation, RMS-1l sets’ the 
RBF field to the address of a location in the stream's I/0 
buffer where your program can build the next record. 
However, if there is not enough room in the buffer to con- 
tain another record (based on the value in the FAB MRS 
field), RMS-1l1 changes RBF to UBF, thereby pointing your 
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program to the user buffer to build the next record. Then, 
during the next put, RMS-11 fills out the current I/0 buffer 
from the UBF buffer, writes the I/O buffer to the file, and 
then starts a new I/O buffer with the data left in the UBF 
buffer, setting RBF back into the I/O buffer. 


4.20.2 Input Values 


The UBF field must contain the address of a buffer in your. program. 


The buffer should be large enough to contain the largest record in the 
file. 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


4.20.3 Initialization and Default 
Macro takes the form: 
RSUBF label 


If there is no initialization macro, UBF = 0. 


Record Access Block (RAB): UBF 4-33 


REKKKRKKKKKKKRK 


* * 
* USZ * 
* x 
KEKKKEKKKKKKAKK 


4.21 USZ 


The one-word User Buffer Size (USZ) field contains the size, in bytes, 
of the buffer indicated by the UBF field. 


4.21.1 Use 


Input to: 
SGET 
You set the USZ field equal to the size of the buffer you 
are providing to hold a record. RMS-11 reads in only the 
number of bytes specified. 
SPUT 


During Locate Mode operations on Sequential files only. See 
discussion under "Use" for the UBF field. 


4.21.2 Input Values 


MINIMUM 1 


MAXIMUM 65535, but maximum record size is also affected by file 


Structure, file organization, and task address space. 
See the RMS-11 User's Guide. 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


4.21.3 Initialization and Default 
Macro takes the form: 
RSUSZ numeric 


If there is no initialization macro, USZ = 0. 
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EXTENDED ATTRIBUTE BLOCKS 


The initialization macros (this chapter) and the field access macros 
(Chapter 7) are provided so that you do not have to know the specific 
position and to a large extent, the size of each field in a XAB. You 
can, therefore, treat the fields as logical entities. It is also pos- 
sible that the positions and sizes of the fields will change from re- 
lease to release of RMS-1l1. 


However, you can determine the position of any field in a XAB as an 
offset from the XAB's starting address. RMS-11 represents these off- 
set values with symbols in one of the following forms: 


e OS$fnm 


where fnm is the three-letter name of a one-byte or one-word field; 
fnm is the name used to reference the field in the initialization 
and field access macros. 


Example OSsTS for the status code field 
e oOSfnmx 
where £nm is the name of a multiword field; fnm is the name _ used 
to reference the field in the initialization and field 


access macros. 


x is a number associated with an individual word in the 
field, from 0 through the end of the field. 


Example OSSIZO for the size of the first segment in a key as’- the 
most significant word 


The values of these symbols can be found in the symbol table of an as- 
sembly listing file for any module containing the XAB. 


5.1 Allocation Extended Attribute Block 


Each Allocation XAB describes an area of a file. An area is a portion 
of an RMS-11 file that is treated as a separate entity for purposes 
of: 


Initial allocation 
Extension 
Placement 

Bucket size 


See also the RMS-11 User's Guide. 


Sequential and Relative files are always composed of a single area 
(Area 0), while Indexed files should contain more than one area. 


Allocation XABs enable you to control: 


e The physical placement of an RMS-11 file of any organization on a 
disk volume: 


You provide one (for any type of file) or more (for Indexed files 
only) Allocation XABs linked to the FAB you use to create the file. 
Within each XAB are two fields: 


Alignment Block Type (ALN) 
Allocation Starting Point (LOC) 


If the ALN field is not zero when the SCREATE macro is executed, 
RMS-11 uses the values in the two fields to direct the placement of 
the first block of the area on the device specified; the XAB ALQ 
field controls the size of the initial allocation. 


NOTE 
On RSTS/E, the File Processor allows RMS-11 to place only 
Area 0. RMS-11 allocates all other areas as extents of 
Area 0. See also comments for the AOP field in this’ sec- 
tion. 


e The internal structure of an Indexed file: 


Whether or not you use placement control, you can use Allocation 
XABS to define multiple areas within an Indexed file, assign the 
index and data levels of the various indexes to particular areas, 
and vary the size of buckets for each area. 


Allocation XABsS are completely optional. If you do not require either 
placement control or an optimized Indexed file, do not include Alloca- 
tion XABs in your XAB chain; RMS-11 uses the following defaults: 


@ RMS-11 creates the file as a single area, using the value in the 


FAB ALQ for the initial allocation quantity. The default extension 
quantity is derived from the FAB DEQ field. The operating system 
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completely controls the physical placement of the file on the disk 
volume. 


e For Indexed files, RMS-1l sets up a single bucket size and_ stores 
buckets of all types (index, SIDR, and user data record) in the 
Single area of the file. 


If you do use Allocation XABs, they are used as: 


Input to SCREATE and SEXTEND 

Before the initiation of a S$CREATE macro, all Allocation 
XABS must be set up and included in the XAB chain linked in 
dense ascending order by AID field: the XAB for Area 0 must 
be the first Allocation XAB in the chain; the XAB for Area 
1 must be next; and so on. The NXT field for Area 0's  XAB 
must point to Area 1's XAB, Area 1's XAB NXT field must 
point to Area 2's XAB, and So on. 


Output from SDISPLAY, SEXTEND, and S$OPEN 

If you want one or more area definitions, link a_ sufficient 
number of Allocation XABs,. RMS-11 sets the appropriate 
fields to the values established when the file was created. 
The Allocation XABs must be adjoining, linked in ascending 
order, but they do not have to be densely ordered. 
Therefore, you can link Allocation XABs for Areas 1 and 3 
only, for example, if descriptions of those areas are the 
only ones you want. 


NOTE 


Since RMS-11]1 creates a file with areas by allocating Area 0 
first and then extending the file for each additional area, 
you can't have a contiguous file with multiple areas on 
RSTS/E. However, after you create the file with areas, you 
can use PIP to copy it into a contiguous space. 


Table 5-l: Allocation Extended Attribute Block Fields 


Field| Field Default Description 
Name Size 


0 Area id number 

0 Alignment block type 
0 Allocation quantity 
0 Allocation options 


1 record Area bucket size 
N/A All XAB length 
N/A XAB type 
0 Area extension quantity 
0 Number of block specified by ALN 
0 Next XAB 
0 Not used 
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5.1.1 AID 


The one-byte Area Identification Number (AID) field identifies the 
area described by the XAB. 


5.1.1.1 Use 
Input to: 


SCREATE/SEXTEND 
You set the AID field to tell RMS-11 the area defined by the 
XAB. 


SDISPLAY/SOPEN 
You set the AID field to tell RMS-11 the area whose descrip- 
tion it should set into the fields of the XAB. 


Additionally, RMS-11 uses the AID field to check the sequencing of the 
Allocation XABS in the chain before continuing with the file 


operation; if the XABs are out of sequence, RMS-11 terminates the op- 
eration. 


5.1.1.2 Input Values 


MINIMUM 


O* 


MAXIMUM 254 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (See Chapter 7). 


5.1.1.3 Initialization and Default - Macro takes the form: 
XSAID numeric 


If there is no initialization macro, AID = 0. 


*Zero is the only value acceptable for Sequential and Relative files. 
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5.1.2 ALN 
The one-byte Alignment Block Type (ALN) field determines whether 


placement control is used in the allocation of blocks in this area by 
the file operation. 


5.1.2.1 Use 


Input to: 
SCREATE 
e If you want placement control over the initial allocation 
of the area, you set the ALN field to indicate that the 
number in the LOC field is one of the following: 
Device Cluster Number 
Logical Block Number 
Virtual Block Number 
Cylinder number on VAX 
The AOP field also affects placement control. 
e If you do not want placement control, you set the ALN 
field to zero. 
SEXTEND 


e If you want placement control over the explicit extension 
of the area, you set the ALN field to indicate that the 
block number in the LOC field is either a Logical Block 
Number or a Virtual Block Number. The AOP field also af- 
fects placement control. 


e If you do not want placement control, you set the ALN 
field to zero.} 


Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the ALN field equal to the value specified when 
the file was created. 
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5.1.2.2 Input Values - The ALN field must contain one of the follow- 


ing: 
zero 


XBSLBN 


XBSVBN 


XBSCYL 


no placement control 


RMS-11 requests the operating system to place the first 
block of the specified allocation on or near the logical 
block / device cluster indicated by the number in the 
Loc field. 


RMS-11 requests the operating system to place the first 
block of the specified allocation near the virtual block 
of the file indicated by the LOC field; not valid during 
SCREATE when the AID field is zero, that is, for Area 0. 


RMS-11 requests the operating system to place the first 
block of the specified allocation at the first block of a 
cylinder as indicated by the LOC field. VAX only 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


5.1.2.3 Initialization and Default - Macro takes the form: 


XSALN symbolic 


If there is no initialization macro, ALN = 0. 


5.1.2.4 Comments - On RSTS/E, you can specify location information 
for Area 0 only. If RMS-11 detects nonzero values in the ALN and LOC 
fields in other Allocation XABs, it returns the error code ERSALQ. 
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5.1.3 ALQ 
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* * 
* ALO * 
* * 
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The two-word Allocation Quantity (ALQ) field contains the size of the 
area represented by the XAB, in blocks. 


5.1.3.1 Use 


Input to: 


SCREATE 


You set the ALQ field equal to the number of blocks to be 
allocated in the initial extent of the area. 


SEXTEND 


You set the ALQ field equal to the number of blocks to be 
added to the area. 


Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the ALQ field equal to the number of blocks” un- 
used in the current extent of the area (see "Comments"). 


RMS-11 obtains this information from the file Prologue. 


5.1.3.2 Input 


SCREATE 


MINIMUM 


MAXIMUM 


SEXTEND 


MINIMUM 


MAXIMUM 


Values 


0, meaning that this area will only be as long as ne- 
cessary; that is, Area 0 will contain the file Pro- 
logue and all other areas will be allocated with no 
blocks. 


number of free blocks on the device containing the 
file. 


1, meaning that one block should be added to the area 
(although a zero extent is possible, it is not logi- 
cal) 


number of free blocks on the device containing the 
area. 
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RMS-11 rounds values up to a multiple of area bucket size. 


A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 


5.1.3.3 Initialization and Default - Macro takes the form: 
XSALQ numeric 


If there is no initialization macro, ALO = 0. 


5.1.3.4 Comments 


@ When Allocation XAB(s) are linked to a FAB, create and extend oper- 
ations ignore the FAB ALQ field, using the XAB ALQ field(s) for the 
particular area(s). If you include only one Allocation XAB, for 
Area 0, RMS-11 uses the ALQ field in the XAB instead of the FAB for 
the size of Area 0, which is essentially the whole file. 


@ The current extent of an area is the number of blocks that were 


last added to the area, via either automatic or explicit extension. 
It is, therefore, not necessarily the total size of the area. 
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5.1.4 AOP 


The one-byte Allocation Options (AOP) field contains a bit string in- 
dicating the type of allocation RMS-11 makes during the file opera- 
tion. 


5.1.4.1 Use 


Input to SCREATE/SEXTEND: 
You set the AOP field to indicate how exact you require the actu- 
al alignment of the area's allocation with the value specified in 
the LOC field. 


Output from SDISPLAY/SOPEN: 


RMS-11 sets the AOP field equal to the value specified when the 
file was created. 


5.1.4.2 Input Values - The AOP field may contain one or both of the 
following symbolic values: 


XBSHRD The operation fails unless the allocation starts exactly 
at the Device Cluster /Logical Block Number specified by 
the LOC field; valid only if the ALN field contains 
XBSLBN. 


XBSCTG The operation fails unless the allocation is contiguous 
within itself. 


A value can be set in the field with the initialization macro shown 
below or with the SSET field access macro (see Chapter 7). 


5.1.4.3 Initialization and Default - Macro takes the form: 
XSAOP symbolic[!symbolic] 
If there is no initialization macro, AOP = 0, meaning: 
e Allocation is made as close to the requested block as possible. 


e Allocation is not necessarily contiguous with the current extent of 
the area. 
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* * 
* BKZ * 
* * 
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5.1.5 BKZ 


The one-byte Bucket Size (BKZ) field contains the size of a bucket, in 
disk blocks, in the area represented by the XAB. 


5.1.5.1 Use - RMS-1l uses the BKZ field for Relative and Indexed 
files. 


Input to: 


SCREATE 
You set the BKZ field equal to the number of disk blocks in 
a bucket for the area to be created. 


Output from: 
SDISPLAY/SOPEN 
RMS-11 sets the BKZ field equal to the bucket size esta- 


blished for the area when the file was created. RMS-11 ob- 
tains the information from the file Prologue. 


5.1.5.2 Input Values - 


MINIMUM = 0, meaning that RMS-11 calculates a size so that a bucket 
contains at least one record. 


MAXIMUM = number of blocks allowed by the operating system (specifying 
a larger value results in error code ERSBKZ): 


IAS = 32 blocks 
RSTS/E = 15 blocks 
RSX-11M = 32 blocks 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (See Chapter 7). 


5.1.5.3 Initialization and Default - Macro takes the form: 
XSBKZ numeric 


If there is no initialization macro, BKZ = minimum number of blocks to 
contain one record. 
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5.1.5.4 Comments - 


e When Allocation XABs are linked to a FAB, RMS-1l1 ignores the FAB 
BKZ field, using the XAB BKZ fields for the particular areas. 


e You gain no particular advantage from different bucket sizes for 
different areas. 
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* BLN “ 
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5.1.6 BLN 
The XABSB macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 

CAUTION 


DO NOT CHANGE THE BLN FIELD. 


5.1.6.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11l 
aborts the operation with a ERSBLN error code. 
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* * 
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5.1.7 CoD 
The XABS$B macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XBSALL. 

CAUTION 


DO NOT CHANGE THE COD FIELD. 


5.1.7.1 Use - Before RMS~11l uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ERSCOD error code. 
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5.1.8 DEQ 


The one-word Default Extension Quantity (DEQ) field contains’ the 
number of blocks RMS-11 requests whenever it automatically extends the 
area (opposed to an explicit extend operation). RMS-1l requests addi- 
tional blocks from the operating system* whenever a task attempts a 
put or update operation and there is not enough room in the area _ re- 
presented by the XAB to complete the operation. 


5.1.8.1 Use - RMS-11 uses the DEQ field for Indexed files only. 
Input to: 


SCREATE 
You set the DEQ field equal to the number of blocks’ that 
Should be requested in each automatic extension of the area 
to be created. 


SOPEN 
You set the DEQ field equal to the number of blocks to be 
used by RMS-11 as a temporary default extension quantity 
until the area is closed; the area attribute is not 
changed. 


Output from: 


SOPEN 
If the DEQ field is zero, RMS-11l sets it equal to the number 
of blocks established as the default extension quantity when 
the area was created. 


5.1.8.2 Input Values - Default extension quantity should be a multi- 
ple of bucket size; RMS-11 rounds it up to the nearest multiple any- 
way before it sends the extension request to the operating system. 


MINIMUM = 0, meaning that whenever RMS-1l has to extend the area, it 
will request the minimum blocks necessary to complete the 
current operation, that is, one bucket. 


MAXIMUM 65,535 blocks 


*Automatic extension can fail;see "Comments." 
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RMS-11 rounds value up to a multiple of area bucket size. 


A value can be set in the field with the initialization macro 
below or with the $STORE field access macro (see Chapter 7). 


5.1.8.3 Initialization and Default - Macro takes the form: 
XSDEQ numeric 


If there is no initialization macro, DEQ = QO. 


5.1.8.4 Comments 


e When Allocation XABs are linked to a FAB, RMS-1l1 uses the XAB 


shown 


DEQ 


field whenever an area has to be extended automatically, unless 
that field is zero; in that case, RMS-11l uses the value in the FAB 


DEQ field. 


e Automatic extension can fail for at least the following reasons; 


there might be others: 
-- Operating system is RSTS/E and file is: 


contiguous; error code = ERSPRV 
shared; error code = ERSPRV 


-- No more room is available on the storage device; error code = 


ERSFUL 


e On the RSTS/E operating system, area allocation is done in 
clusters; see the RMS-11 User's Guide for a discussion of the in- 


teraction between clusters and default extension quantity. 


e See the RMS-11 User's Guide for a discussion of default extension 


quantity and its optimization. 
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5.1.9 LOC 


The two-word Allocation Starting Point (LOC) field contains a number 
interpreted by RMS-11l as the Device Cluster, Logical Block, Virtual 
Block, or cylinder number (depending on the value of the ALN field) 
where the allocation specified by the operation should start. The ALQ 
field specifies the allocation quantity and the AOP field indicates 
how definite the placement is. 


5.1.9.1 Use 
Input to: 


SCREATE/SEXTEND 
If you specify a nonzero value for the ALN field, you must 
set the LOC field equal to the appropriate number (depending 
on the value in the ALN field) where you want the specified 
allocation to begin. 


5.1.9.2 Input Values - The LOC field must contain one of the follow- 
ing: 


e any value* if the ALN field is zero 
@e numeric value within the range: 


MINIMUM = 0; if the ALN field contains XBSVBN, RMS-1l requests 
placement near the current end of the file, unless AID 
is zero. 

number of free blocks / clusters on the device contain- 

ing the file, if the ALN field contains XBSLBN 


MAXIMUM 


= number of cylinders on the device containing the file, if 
the ALN field contains XBSCYL 


= number of blocks currently in the file, if the ALN field 
contains XBSVBN 


e the numeric value -1 if the ALN field contains XBSCYL; RMS-11 re- 
quests placement at the first block of any cylinder 


*Recommended value is the default, zero. 
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A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (See Chapter 7). 


5.1.9.3 Initialization and Default - Macro takes the form: 


XSLOC numeric 


If there is no initialization macro, LOC = 0. 
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5.1.10 NXT 

The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-11 that there is at 
least one more XAB in the chain connected to the FAB via the FAB’ XAB 


field. See "Linking and Ordering XABs" at the beginning of this 
chapter. 


5.1.10.) “Use 
Input to: 
SCREATE/SDELETE/SEXTEND/SOPEN 

e If you have allocated another XAB and want RMS-11 to use 
it, you set the NXT field equal to the address of that 
XAB, 

e If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11]1 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 


if that area is not a valid XAB, RMS-1l returns the error 
code ERSXAB. 


5.1.10.2 Input Values - The NXT field must contain either: 
e zero (0) = there are no more XABs in this chain 


e address of an Extended Attribute Block separately allocated in the 
program 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


5.1.10.3 Initialization and Default - Macro takes the form: 


XSNXT label 


If there is no initialization macro, NXT = 0. 
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* * 
> VOL * 
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5.1.11 VOL 


The one-word Relative Volume Number (VOL) field is currently not used 
by RMS-1ll. 


5.1.11.1 Use - NONE 


5.1.11.2 Input Values - NONE 


5.1.11.3 Initialization and Default - NONE 


5.1.11.4 Examples - NONE 


5.1.11.5 Comments - NONE 
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5.2 Date Extended Attribute Block 


The Date XAB contains date and time information about the creation and 
revision of the file, as well as an RMS-11 revision number. The in- 
formation is output only by RMS-11 during a S$DISPLAY or SOPEN opera- 
tion; RMS-11 obtains the data from the file attributes. 


Table 5-2: Date Extended Attribute Block Fields 


Field 
Name 


















Description 


DAT XAB length 
Creation date-time 

XAB type 

Next XAB 

Revision date-time 
RMS-11 revision number 


1 eceenetamtemonnechs nt tin 
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5.2.1 BLN 


The XABSB macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 


CAUTION 


DO NOT CHANGE THE BLN FIELD. 


5.2.1.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ERSBLN error code. 
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5.2.2 CDT 


The four-word Creation Date (CDT) field contains the date and time the 
file associated with the linked FAB was created. 


5.2.2.1 Use 
Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the CDT field equal to the creation date it 
finds in the file attributes. 


5.2.2.2 Output Values - The value RMS-11 puts into the CDT field is 
an eight-byte binary number representing the number of hundreds of na- 
noseconds that elapsed between November 17, 1858*, and the time _ the 
file was created. 


This method of storing dates is standard for DIGITAL operating sys- 
tems, although it has not been implemented in IAS, RSTS/E, or RSX-11M 
yet**, RMS-11 translates the dates these operating systems do main- 
tain into the 64-bit format before storing it in the Date XAB. The 
resultant date is only as accurate as the operating system date: 


TAS accurate to the second 
RSTS/E accurate to the minute 
RSX-lL1IM accurate to the second 


Appendix C contains a MACRO-11 routine for converting this 8-byte bi- 
nary number to ASCII characters; this is the same routine used by 
RMSDSP (see the RMS-1l User's Guide). 


*The Smithsonian Astrophysical Base Date, celebrating the day the 


first photographic plate was exposed at the Harvard Smithsonian Ob- 
servatory. 
**Tt has been implemented in the VAX/VMS System. 
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5.2.3 COD 
The XABSB macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XBSDAT. 

CAUTION 


DO NOT CHANGE THE COD FIELD. 


5.2.3.1 Use - Before RMS~11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
terminates the operation with a ERSCOD error code. 
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5.2.4 NXT 

The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-1l that there is at 
least one more XAB in the chain connected to the FAB via the FAB’ XAB 


field. See "Linking and Ordering XABs" at the beginning of this 
chapter. 


5.2.4.1 Use 
Input to: 
SCREATE/SDELETE/SEXTEND/SOPEN 

e If you have allocated another XAB and want RMS-11 to’ use 
it, you set the NXT field equal to the address of that 
XAB. 

e If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 


if that area is not a valid XAB, RMS-11 returns error 
code ERSXAB. 


5.2.4.2 Input Values - The NXT field must contain either: 
e zero (0) = there are no more XABs in this chain 


@e address of an Extended Attribute Block separately allocated in the 
program 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (See Chapter 7). 


5.2.4.3 Initialization and Default - Macro takes the form: 


XSNXT label 


If there is no initialization macro, NXT = 0. 
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The four-word Revision Date (RDT) field contains the date and time the 
file associated with the linked FAB was last updated, that is, the 
date and time the last write record operation* was executed against 
the file. 


5.2.5.1 Use 
Output from: 


SDISPLAY/$OPEN 
RMS-11 sets the RDT field equal to the revision date it 
finds in the file header. 


5.2.5.2 Output Values - The value RMS-11 puts into the CDT field is 
an eight-byte binary number representing the number of hundreds of na- 
noseconds that elapsed between November 17, 1858%**, and the time the 
file was created. 


This method of storing dates is standard for DIGITAL operating sys- 
tems, although it has not been implemented in IAS, RSTS/E, or RSX-11M 
yet***, RMS-11 translates the dates these operating systems do main- 
tain into the 64-bit format before storing it in the Date XAB. The 
resultant date is only as accurate as the operating system date: 


IAS accurate to the second 


RSTS/E accurate to the day 
RSX-11M accurate to the second 


Appendix C contains a MACRO-11 routine for converting this 8-byte bi- 
nary number to ASCII characters; this is the same routine used by 
RMSDSP (see the RMS-11 User's Guide). 

*Includes RMS-11 delete, put, and update operations and any non-RMS-11 
operations, such as FCS, BASIC+, and utilities (PIP and so on). 
Since higher-level language statements eventually break down to 
RMS-l1l1 macros, the revision date is valid no matter the source 
language of the program doing the file revision. 

**The Smithsonian Astrophysical Base Date, celebrating the day the 
first photographic plate was exposed at the Harvard Smithsonian Ob- 
servatory. 

***Tt has been implemented in the VAX/VMS System. 
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5.2.6 RVN 


RMS-11 returns valid data to the RVN field only on IAS and RSX-11M op- 
erating systems. On RSTS/E systems, this field is always zero. The 
one-word Revision Number (RVN) field indicates the number of times the 
file has been opened for write operations by RMS-11* and non-RMS-11 
tasks since it was created (that open is therefore not counted). 


5.2.6.1 Use 
Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the RVN field equal to the revision number it 
finds in the file header. 


5.2.6.2 Input Values - The value stored in the RVN field is a_ simple 
binary number, easily translated to octal or decimal (see subroutines 
in the sample program in Appendix B). 


*If the FAB FAC field contains FBSDEL, FBSPUT, FBSUPD, and/or FBSWRI, 
the operating system increments the revision number in the file 
header during an open operation. 
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5.3 Key Extended Attribute Block 


A Key XAB describes one key of an Indexed file. This includes specif- 
ications for the key field (type, position, length) as well as the 
index structure supporting that key. See the RMS-1ll User's Guide. 


Key XABs are used as: 


Input to SCREATE 
Before the initiation of a SCREATE macro, if the FAB’ ORG 
field contains FBSIDX, you must link at least one Key XAB to 
the FAB to define the Primary Key. You must also use one 
Key XAB to define each additional key you want the file to 
have. If you specify more than one Key XAB, they must be: 


e linked in densely ascending order by REF field; that is, 
the Primary Key XAB is the first Key XAB to occur in the 
chain, the First Alternate Key XAB next, and so on 


e adjoining in the XAB chain; that is, the Primary Key XAB 
NXT field points to the First Alternate Key XAB, the 
First Alternate Key XAB points to the Second Alternate 
Key XAB, and so on 


Output from $DISPLAY and SOPEN: 
If you want one or more key definitions, link in a_e suffi- 
cient number of key XABs. RMS-11 sets the appropriate 
fields to the values established when the file was created. 
If there is more than one, the Key XABS must be: 


e linked in ascending order by REF field, but not necessar- 
ily densely; for example, if you only want descriptions 
of the Second and Fourth Alternate Keys, you must link 
only the XABs for those keys, in that order 


e adjoining in the XAB chain; that is, the first Key XAB 
in the chain must point to the second one, and so on 
NOTE 


Since Key XABs describe both keys and their indexes, the 
terms: 


"key described by the XAB" 
"index described by the XAB" 


are used in the following field descriptions; they both 


refer to the same XAB. The value in the REF field deter- 
mines which key/index is described. 
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Table 5-3: Key Extended Attribute Block Fields 


Field| Field Default 
Name Size 


N/A 
N/A 











Description 








ct hts Nera 


KEY XAB length 

XAB type 

Level 0 area number 
Data bucket size 
Level 0 £111 number 
Key data type 

VBN of first data bucket 
Key characteristics 
Levels 2+ area number 
Index bucket size 

Levels 2+ fill number 
Pointer to key name 
Level 1 area number 
Index level of root 
Minimum length record size 
Number of key segments 
Null key value 

Next XAB 

Key position(s) in record 
Key described by XAB 

VBN of index root 

Size(s) of key segments 
Total key size 
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5.3.1 BLN 
The XABSB macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 

CAUTION 


DO NOT CHANGE THE BLN FIELD. 


5.3.1.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ERSBLN error code. 
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52.3.2) COD 
The XABSB macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XBSKEY. 

CAUTION 


DO NOT CHANGE THE COD FIELD. 


5.3.2.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ERSCOD error code. 
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5.3.3 DAN 


The one-byte Data Area Number (DAN) field contains the number of the 
file area in which Level 0* of the index described by this XAB is (or 
will be) stored. 


5.3.3.1 Use 
Input to: 
SCREATE 


e If you are not creating a multi-area file**, that is, no 
or one Allocation XAB, ensure that the DAN field is zero 
(the default). 


e If you are creating a multi-area file, that is, there are 
multiple Allocation XABs also linked to the FAB, set the 
DAN field to the number of the area in which you want the 
data level of this index (set by REF field) stored. This 
number must be the same as the AID field of one of the 
Allocation XABs. 


Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the DAN field equal to the number of the area in 
which Level 0O of the index indicated by the REF field is 
stored. 


5.3.3.2 Input Values 
MINIMUM = 0, meaning Area 0** 


MAXIMUM = 254, meaning the maximum possible area that may be 
allocated; however, the maximum within each program 
is restricted to the highest number in an Allocation 
XAB AID field 


*The data level (Level 0) of the Primary index contains your data re- 
cords while Level 0 of Alternate indexes contain Secondary Index Data 
Records that point into the Primary index Level 0. See the RMS-11 
User's Guide. 

**If there are no Allocation XABs, the entire file is in Area 0. 
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A value can be set in the field with the initialization macro 


shown 
below or with the SSTORE field access macro (see Chapter 7). 


5.3.3.3 Initialization and Default -—- Macro takes the form: 


XSDAN numeric 


If there is no initialization macro, DAN = 0. 
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5.3.4 DBS 
The one-byte Data Bucket Size (DBS) field contains the number of 


blocks in a bucket in the file area that contains Level 0 of the index 
described by this XAB. 


5.3.4.1 Use 
Output from: 
SDISPLAY/SOPEN 
RMS-11 sets the DBS field equal to the bucket size of the 


area established for Level 0 of this index when the file was 
created. 


5.3.4.2 Output Values 


MINIMUM J 


MAXIMUM number of blocks allowed by the operating system 
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5.3.5 DFL 


The one-word Data Bucket Fill Number (DFL) contains the number of 
bytes in each bucket of this index's Level 0 that should be used to 
store data if the RAB ROP field contain RBSLOA when the Record Access 
Stream is set up (SCONNECT); if RBSLOA is not set, RMS-11 ignores the 
fill number. See the RMS-11 User's Guide for a discussion of fill 
numbers. 


5.3.5.1 Use 
Input to: 


SCREATE 
You set the DFL field equal to the number of bytes you want 
filled in each Level 0 bucket when RMS-11 is honoring fill 
numbers. 


Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the DFL field equal to fill number’ established 
for Level 0O of the index designated by the REF field when 
the file was created. 


5.3.5.2 Input Values 


MINIMUM = 0, meaning the buckets should be completely filled regard- 
less of value in RAB ROP field 


= half of the bytes in the bucket; this is a logical minimum, 
meaning you can specify less, but RMS-11 ignores it, supply- 
ing its own 50% figure 


MAXIMUM 


total number of bytes in a bucket less one record (including 
overhead); this is a logical maximum; the physical maximum 
(total number of bytes in a bucket) can be achieved by spec- 
ifying zero 
You can figure the number of bytes in a bucket as follows: 

NRBKT = 512*BKS 


where BKS is the bucket size, expressed in blocks. 
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A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


5.3.5.3 Initialization and Default - Macro takes the form: 


XSDFL numeric 


If there is no initialization macro, DFL = 0. 
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5.3.6 DTP 
The one-word Key Data Type (DTP) field contains a bit string indicat- 
ing the data type of the key described by this XAB. 
CAUTION 
If you are currently using RMS-11K V1.5 and want to use the 


DTP field, you must reassemble your program using the 
RMS-11K V1.8 RMSLIB.MLB. 


5.3.6.1 Use 
Input to: 
SCREATE 
You set the DTP field to indicate the data type of the key 
you have defined with the POS and SIZ field. 
Output from: 
SDISPLAY/SOPEN 
RMS-11 sets the DTP field to indicate the data type esta- 


blished for the key indicated by the REF field when the file 
was created. 


5.3.6.2 Input Values —- The DTP field must contain one of the _ follow- 
ing symbolic values: 


XBSBN2 Each 16-bit unsigned binary key requires two bytes. 
XBSBN4 Each 32-bit unsigned binary key requires four bytes. 
XBSIN2 Each 15-bit signed integer key requires two bytes. 

XBSIN4 Each 31-bit signed integer key requires four bytes. 


XBSPAC A packed decimal key has two decimal digits stored in 
each byte. 


XBSSTG Each character of a string key is stored as a binary 
value. 


A value can be set in the field with the initialization macro shown 
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below or with the $SET field access macro (see Chapter 7). 


5.3.6.3 Initialization and Default - Macro takes the form: 


XSDTP symbolic 


If there is no initialization macro, DTP = XBSSTG. 
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5.3.7 DVB 
The two-word Data Virtual Block Number (DVB) field specifies the 


number of the file's virtual block that contains the first block of 
the first* bucket in Level 0 of the index described by this XAB. 


5.3.7.1 Use 
Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the DVB field equal to the number of the virtual 
block containing the first data from this index in the file. 


5.3.7.2 Output Values 


MINIMUM = first data block in the file (after the Prologue) if the 
index is Primary 
MAXIMUM = last block in the file 


*Based on physical ordering from the beginning of the file. 
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5.3.8 FLG 


The one-word Flags (FLG) field contains a bit string indicating char- 
acteristics of the key described by the XAB. 


5.3.8.1 Use 
Input to: 


SCREATE 
You set the FLG field to indicate the characteristics you 
want associated with the key described by the REF field. 


Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the FLG field to indicate the key characteris- 
tics established when the file was created. 


5.3.8.2 Input Values - The FLG field may contain one or more of the 
following symbolic values: 


XBSCHG the value in the key field described by this XAB may be 
changed during an update operation; valid only for Al- 
ternate Keys (REF field greater than 0) and in conjunc- 
tion with XBSDUP 


XBSDUP more than one record within the file may have the same 
value in the key field described by this XAB 


XBSNUL if the string key described by this XAB is completely 
filled with the character in the NULL field or the in- 
teger, binary, or packed decimal key is zero, RMS-11 
makes no entry in the index for the record; valid for 
Alternate Keys only 
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RMS-11 restricts the combination of XBSCHG and XBSDUP as follows: 
Combination 


XBSCHG XBSCHG Default Default 
+ 


+ + + 
Key Type XBSDUP Default XBSDUP Default 
Primary Error Error Allowed Allowed 
Alternate Allowed Error Allowed Allowed 


A value can be set in the field with the initialization macro shown 
below or with the $SET field access macro (see Chapter 7). 


5.3.8.3 Initialization and Default - Macro takes the form: 
X$FLG symbolic[!symbolic[!symbolic} ] 
If there is no initialization macro, FLG = 0, meaning: 
e For Primary Key, duplicate keys are not allowed. 
e For Alternate Keys 
-- duplicate keys allowed 
-- key values may change during update operation 


-- no null key value 


5.3.8.4 Comments 

e At all times, for Primary Keys: 
-- key values cannot change during update operation 
-- no null key values 

e Since the FLG field is a bit string, values cannot be added to the 
field with the SSTORE field access macro. You should use the S$SET 


field access macro (see Chapter 7). However, you use the SSTORE 
Macro to (re)set all bits in the field. 
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5.3.9 IAN 


The one-byte Index Area Number (IAN) field contains the number of the 
file area in which Levels 2+ of the index described by this XAB are 
(or will be) stored. 


5.3.9.1 Use 
Input to: 
SCREATE 


e If you are not creating a multi-area file*, that is, no 
or one Allocation XAB, ensure that the IAN field is zero 
(the default). 


e If you are creating a multi-area file, that is, there are 
multiple Allocation XABs also linked to the FAB, set the 
IAN field to the number of the area in which you want the 
index levels two and up of this index (set by REF field) 
stored. This number must be the same as the AID field of 
one of the Allocation XABs. 


Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the IAN field equal to the area in which Levels 
2+ of the index indicated by the REF field are stored. 


5.3.9.2 Input Values 

MINIMUM = 0, meaning Area 0* 

MAXIMUM = 254, meaning the maximum possible area that may be 
allocated; however, the maximum within each program is 
restricted to the highest number in an Allocation XAB 
AID field 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (See Chapter 7). 


*If£ there are no Allocation XABs, the entire file is in Area 0. 
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5.3.9.3 Initialization and Default - Macro takes the form: 
XSIAN numeric 


If there is no initialization macro, IAN = 0. 
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5.3.10 IBS 
The one-byte Index Bucket Size (IBS) field contains the number of 


blocks in a bucket in the one or two file areas that contain Levels 1+ 
of the index described by this XAB. 


5.3.10.1 Use 
Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the IBS field equal to the bucket size of the 
area(s) established for Levels 1+ of this index when the 
file was created. 


5.3.10.2 Output Values 


MINIMUM 


1 


MAXIMUM 


number of blocks allowed by the operating system 


Key XAB: IBS 5-43 


KRREKRKKEKKKRREKEESE 


x * 
* IFL = 
* * 
KKKKKKEKEKKEKEEE 


5.3.11 IFL 


The one-word Index Bucket Fill Number (IFL) contains the number of 
bytes in each bucket of this index's Levels 1+ that should be used to 
store index information if the RAB ROP field contains RBSLOA when’ the 
Record Access Stream is set up (SCONNECT); if RBSLOA is not set, 
RMS-11 ignores the fill number. See the RMS-1l1 User's Guide for a 
discussion of fill numbers. 


5.3.11.1 Use 
Input tos 


SCREATE 
You set the IFL field: equal to the number of bytes you want 
filled in each Levels 1+ bucket when RMS-11 is honoring fill 
numbers, 


Output from: 
SDISPLAY/SOPEN 
RMS-11 sets the IFL field equal to fill number’ established 


for Levels 1+ of the index designated by the REF field when 
the file was created. 


5.3.11.2 Input Values 


MINIMUM = 0, meaning the buckets should be completely filled regard- 
less of the value in the RAB ROP field 
= half of the bytes in the bucket; this is a logical minimum, 
meaning you can specify less, but RMS-11 ignores it, supply- 
ing its own 50% figure 
MAXIMUM = total number of bytes in a bucket less one record (including 


overhead); this is a logical maximum; the physical maximum 
(total number of bytes in a bucket) can be achieved by spec- 
ifying zero 

You can figure the number of bytes in a bucket as follows: 


NRBKT = 512*BKS 


where BKS is the bucket size, expressed in blocks. 
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A value can be set in the field with the initialization macro 


shown 
below or with the SSTORE field access macro (see Chapter 7). 


5.3.11.3 Initialization and Default - Macro takes the form: 


XSIFL numeric 


If there is no initialization macro, IFL = 0. 
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5.3.12 KNM 


The one-word Key Name Address (KNM) field points to an ASCII string 
that is associated with the key described by this XAB. RMS-11 does 
not use this field for processing, but does store it in the file Pro- 
logue during a create operation and outputs it during $DISPLAY and 
SOPEN. The RMSDSP utility also prints out this string (see the RMS-11 
User's Guide). 


5.3.12.1 Use 
Input to: 
SCREATE 
If you want to associate a name or other identification with 
the key described by this XAB, set the KNM field equal to 
the address of that name. 
SDISPLAY/SOPEN 
e If you do not want to provide a 32-byte buffer to hold 
the key name string, you set the KNM field to zero; 
RMS-11 does not output the key name. 


e If you are providing a buffer for the key name. string, 
you set the KNM field equal to the buffer's address. 


5.3.12.2 Input Values - The KNM field must contain either: 
e zero (0) = no ASCII key name string 


e address of an ASCII string; RMS-11 reads and writes 32 bytes 
starting with this location: 


-- during SCREATE, be sure that you have valid data (if only 
blanks) for that length 


-- during S$DISPLAY and SOPEN, be sure that the indicated buffer is 
at least 32 bytes long or the key name will overlay other data 
or instructions 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 
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5.3.12.3 Initialization and Default - Macro takes the form: 
XSKNM label 


If there is no initialization macro, KNM = 0. 
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The one-byte Lowest Index Level Area Number (LAN) field contains’ the 


number 


of 


the file area in which Level 1 of the index described by 


this XAB is (or will be) stored. 


5.3.13.1 


Input to: 


SCREATE 


Use 


If you are not creating a multi-area file*, that is, no 
or one Allocation XAB, ensure that the LAN field is zero 
(the default). 


If you are creating a multi-area file, that is, there are 
multiple Allocation XABS also linked to the FAB, set the 
LAN field to the number of the area in which you want the 
index level one of this index (set by REF field) stored. 
This number must be the same as the AID field of one of 
the allocation XABs. 


Output from: 


5.3.13.2 


MINIMUM 


MAXIMUM 


SDISPLAY/SOPEN 


RMS-11 sets the LAN field equal to the area in which 
Level 1 of the index indicated by the REF field is 
stored. 


Input Values 


0, meaning the same area as the rest of the index (Levels 


2+), not necessarily Area 0 


1, lowest area number that can be specifically identified 


254, meaning the maximum possible areas that may be allocat- 


ed; however, the maximum within each program is res- 
tricted to the highest number in an Allocation XAB AID 
field 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 
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5.3.13.3 Initialization and Default - Macro takes the form: 
XSLAN numeric 


If there is no initialization macro, LAN = 0. 


5.3.13.4 Comments - The bucket size for the area containing Level 1 
of an index must be the same as the bucket size for the area contain- 
ing the rest of the index (Levels 2+). 
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5.3.14 LVL 


The one-byte Root Level (LVL) field contains the level number of the 
Root bucket of the index described by this XAB. This number is one 
less than the depth of the index. 


5.3.14.1 Use 
Output from: 
SDISPLAY/SOPEN 
RMS-11 sets the LVL field equal to the number of the index 


level of the Root bucket for the index identified by the REF 
field. 


5.3.14.2 Input Values 


MINIMUM = 1, meaning that the index is the shallowest possible, with 
one level of data and one level of index, the Root 
MAXIMUM = no logical limit 
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5.3.15 MRL 


The one-word Minimum Record Length (MRL) field contains the length, in 
bytes, that a record must be to include the key described by the XAB. 


5.3.15.1 Use 
Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the MRL field to the number of bytes in the 
shortest record that can contain the key identified by the 
REF field. 


5.3.15.2 Output Values - The value in the MRL field is based on _ the 
key's position (specified by the POS field) and the key's length (in- 
dicated by the SIZ field). In a single-segment key, the sum of the 
two provides the minimum record length. However, in a multi-segment 
key, the pertinent segment is the one farthest from the beginning of 
the record. The starting position of that segment, plus its length, 
determine the minimum length record. 


5.3.15.3 Comments 


e If the index described by the XAB is the Primary index, then no re- 
cord smaller than the MRL value can be written to the file; RMS-11 
returns error code ERSRSZ. 


e If the index described by the XAB is an Alternate index, then if 


the record is shorter than the MRL, RMS-11 makes no entry in the 
index for the record. 
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5.3.16 NSG 
The one-byte Number of Key Segments (NSG) field contains the number of 


segments specified in the key described by the XAB when the file was 
created. The POS and SIZ fields contain this number of values. 


5.3.16.1 Use 
Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the NSG field equal to the number of positions 
and lengths it finds in the POS and SIZ fields. 


5.3.16.2 Input Values 


MINIMUM 


1 


MAXIMUM 8 


Only string keys will have NSG values greater than l. 
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5.3.17 NUL 


The one-byte Null Key Character (NUL) field contains the binary repre- 
sentation of the null key character for the key described by this XAB. 
This field is valid for string Alternate Keys only (REF field greater 
than 0). See the RMS-11 User's Guide for a discussion of null key va- 
lues. 


5.3.17.1 Use 
Input to: 


SCREATE 
You set the NUL field equal to the character or code you 
want used as the null key character for this key; you 
should also put the symbolic value XBSNUL in the FLG field. 


Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the NUL field equal to the null key value esta- 
blished when the file was created. 


5.3.17.2 Input Values ~- RMS-1l1 uses the NUL field only if the FLG 
field contains XBSNUL and the key is a string data type; if both are 
true, the NUL field must contain* a binary number whose octal value 
ranges from 000 to 377. You may represent an ASCII character (via the 
MACRO-11 single-quote (') convention) or a non-ASCII octal value. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (See Chapter 7). 


5.3.17.3 Initialization and Default - Macro takes the form: 

XSNUL value 
where value is a valid MACRO-1l representation of a one-byte value. 
If there is no initialization macro, NUL = 0. 


*If one of these conditions is false, the NUL may contain any value; 
the recommended value in that case is the default, zero. 
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5.3.17.4 Examples 


e The following code specifies a null key value of Z for a= string 
key: 


KEYDEF: XABS$B XBSKEY 
XSDTP XBSSTG 


X$SFLG XBSNUL 
X$NUL = 'Z 


XABSE 


e The following code specifies the null key feature for a string key, 
but the null key value is the ASCII character DEL: 


KEYDEF: XABSB XBSKEY 
XSDTP XBSSTG 


XSFLG XBSNUL 
XSNUL “177 


XABSE 


e The following code specifies the null key feature for a packed de- 
cimal key; however, no null key value is necessary: 


KEYDEF: XABSB XBSKEY 
XSDTP XBSPAC 


XSFLG XBSNUL 


XABSE 
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5.3.18 NXT 

The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-1ll that there is at 
least one more XAB in the chain connected to the FAB via the FAB XAB 


field. See “Linking and Ordering XABs" at the beginning of this 
chapter. 


5.3.18.1 Use 
Input to: 
SCREATE/SDELETE/SEXTEND/SOPEN 

e If you have allocated another XAB and want RMS-11 to use 
it, you set the NXT field equal to the address of that 
XAB,. 

e If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-1ll interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 


if that area is not a valid XAB, RMS-1ll1 returns the error 
code ERSXAB. 


5.3.18.2 Input Values - The NXT field must contain either: 
e zero (0) = there are no more XABs in this chain 


e address of an Extended Attribute Block separately allocated in the 
program 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


5.3.18.3 Initialization and Default - Macro takes the form: 


XSNXT label 


If there is no initialization macro, NXT = 0. 
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5.3.19 POS 


The eight-word Key Position (POS) field contains the starting  posi- 
tions within the record for all segments of the key described by this 
XAB. Combined with the SIZ and DTP fields, the POS field completely 
defines the key. 


An RMS-11 key string may contain from one to eight segments; all 
other key types require a single segment. Each word in the POS field 
specifies the starting position of a segment: the first word, the 
first segment, the second word, the second segment, and so on. Each 
segment must be contiguous, but the segments do not have to be contig- 
uous with each other. When processing records, RMS-1l1 combines the 
individual segments and treats them as a Single, logically contiguous 
string beginning with the first segment and ending with the last. See 
also the RMS-11 User's Guide discussion of segmented keys. 


5.3.19.1 Use 
Input to: 


SCREATE 
You set the POS field to include the starting position of 
each segment in the key described by this XAB. See "Com- 
ments" for S$STORE syntax. 


Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the POS field to include starting positions of 
the key segments established when the file was created. 


5.3.19.2 Input Values - The POS field must contain at least one num- 
eric value in the range: 


MINIMUM = 0, meaning the segment starts in the first byte of the _ re- 
cord 


MAXIMUM 


65535, meaning the segment starts in the last byte of the 
largest possible record 


If a string key has multiple segments, you must specify a starting po- 
sition for each segment, each within the above range, using the form: 


<seg0,segl[,seg2,...,seg7]> 
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The values do not have to represent ascending byte positions in the 
record. 


A value can be set in the field with the initialization macro shown 


below or with the SSTORE field access macro (see "Comments" below and 
Chapter 7). 


5.3.19.3 Initialization and Default - Macro takes the form: 
XSPOS [<]numeric[,numeric,...>] 


If there is no initialization macro, POS = 0. 


5.3.19.4 Comments 


e You may store or fetch the position of an individual segment in the 
POS field, by using the term 


POSn 


where n is an integer in the range 0 to 7, indicating the segment 
number whose position you want to affect. 


Example You want to check the starting position of the third seg- 
ment of a key string: 


SFETCH RO, POS2,R4 


You want to reset the starting position of the first seg- 
ment of a key string: 


SSTORE RO,POSO,R4 


In both cases, RO is used as a buffer for the position 
number. 
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5.3.20 REF 


The one-byte Key of Reference (REF) field identifies the index and key 
described by this XAB. 


5.3.20.1 Use 
Input to: 
SCREATE/S$EXTEND 
You set the REF field to tell RMS-11 exactly what key and 
index you are describing in the XAB. 
SDISPLAY/SOPEN 


You set the REF field to tell RMS-11 exactly what key and 
index you want RMS-11 to describe in the XAB. 


5.3.20.2 Input Values 


MINIMUM 


0, meaning Primary Key 


MAXIMUM 254 


All values from 1 to 254 indicate Alternate Keys, first, second, and 
so on. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


5.3.20.3 Initialization and Default - Macro takes the form: 


XSREF numeric 


If there is no initialization macro, REF = 0. 
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5.3.21 RVB 
The two-word Root Virtual Block Number (RVB) field specifies’ the 


number of the file's virtual block that contains the Root of the index 
represented by this XAB. 


5.3.21.1 Use 
Output from: 
SDISPLAY/SOPEN 
RMS-11 sets the RVB field equal to the number of the first 


virtual block of the Root bucket for the index indicated by 
the REF field. 


5.3.21.2 Output Values - 


MINIMUM 


first data block of the file, after the Prologue 


MAXIMUM 


last block of the file 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 
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5.3.22 SIZ 


The eight-byte Key Size (SIZ) field contains the lengths, in bytes, of 
all segments of the key described by this XAB. Each byte in the SIZ 
field specifies the size of a segment: the first byte, the first seg- 
ment, second byte, the second segment, and so on. There must be a 
length specified for each segment given a starting position in the POS 
field. 


5.3.22.1 Use 
Input to: 


SCREATE 
You set the SIZ field to include the length of each segment 
in the key described by this XAB. See "Comments" for S$STORE 
syntax. 


Output from: 


SDISPLAY/SOPEN 
RMS-11 sets the SIZ field to include lengths of the key seg- 
ments established when the file was created. 


5.3.22.2 Input Values - The SIZ field must contain at least one num- 
eric value which depends on key data type (specified by the DTP field 
in this XAB), as follows: 


e 15-bit Signed Integer Key Type, SIZ = 0 or 2 
e 31-bit Signed Integer Key Type, SIZ = 0 or 4 
e 16-bit Unsigned Binary Key Type, SIZ = 0 or 2 


e 32-bit Unsigned Binary Key Type, SIZ = 0 or 4 


e String Key Type 


MINIMUM 0 (null segment) 


MAXIMUM 


255 
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If a string key has multiple segments, you must specify a length 
for each segment, using the form: 


<len0O, lenl[,len3,...,len7]> 
The sum of the multiple lengths cannot exceed 255. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


5.3.22.3 Initialization and Default - Macro takes the form: 
XSSIZ [<]numeric[,numeric,...>] 


If there is no initialization macro, SIZ = 0. 


5.3.22.4 Examples 


e The following code specifies a single-segment key eight bytes long: 


KEYDEF: XABSB XBSKEY 


XSSIZ 8. 


XABSE 


e The following code specifies a key with four segments, defining 
their sizes and positions: 


KEYDEF: XABSB XBSKEY 


XSSIZ <8,2,5,32> 
XSPOS <19,0,13, 28> 


XABSE 


5.3.22.5 Comments - You may store or fetch the length of an individu- 
al segment in the SIZ field, by using the term 


SIZn 


where n is an integer in the range 0 to 7, indicating the segment 
number whose length you want to affect. 
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Example You want to check the length of the third segment of a_e key 
string: 


SFETCH RO,SIZ2,R4 


You want to reset the length of the first segment of a _ key 
string: 


SSTORE RO,SIZO,R4 


In both cases, RO is used as a buffer for the length. 
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5.3.23 TKS 


The one-byte Total Key Size (TKS) field specifies the number of bytes 
contained in all segments of the key described by the XAB. 


5.3.23.1 Use 
Output from: 
SDISPLAY/SOPEN 
RMS-11 sets the TKS field equal to the sum of the segment 


lengths established via the SIZ field for the key indicated 
by the REF field. 


5.3.23.2 Input Values 


MINIMUM 


1 


MAXIMUM 255 


Key XAB: TKS 5-63 


5.4 Protection Extended Attribute Block 


The Protection XAB describes the protection code of a file, including 
specifications for the owner's account number. You use a Protection 
XAB generally when you do not want the default protection value _ for 
the operating system applied to the file. 


Protection XABs are used as: 


Input to SCREATE and S$CLOSE 
For an RMS-ll file of any organization, you may set its pro- 
tection code when it is created and change that code when it 
is closed. 


Output from SDISPLAY and SOPEN 
RMS-11 supplies the current protection value for the file. 


Table 5-4: Protection Extended Attribute Block Fields 


Field | Field Description 
Name Size 


se anaemia dren inanimate ont ss 


PRO XAB length 
XAB type 

Next XAB 
Programmer part of account number 
Project part of account number 
File protection value 
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5.4.1 BLN 
The XABSB macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 

CAUTION 


DO NOT CHANGE THE BLN FIELD. 


5.4.1.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the BLN field. If this field does not contain the proper code, RMS-11l 
aborts the operation with a ERSBLN error code. 


Protection XAB: BLN 5-65 


RREKKEKKEKKEKKEKKE 


x * 
* COD * 
x x 
KKAKKKKEKKKEEEE 


5.4.2 COD 
The XABSB macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XBSPRO. 

CAUTION 


DO NOT CHANGE THE COD FIELD. 


5.4.2.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ERSCOD error code. 
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5.4.3 NXT 
The one-word Next XAB (NXT) field, if not zero, points to another sep- 
arately allocated XAB and thereby indicates to RMS-11 that there is at 


least one more XAB in the chain connected to the FAB via the FAB’ XAB 
field. See Chapter 1 at the beginning of this chapter. 


5.4.3.1 Use 
Input to: 
SCREATE/SDELETE/SEXTEND/SOPEN 

e If you have allocated another XAB and want RMS-11l to use 
it, you set the NXT field equal to the address of that 
XAB. 

e If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 


if that area is not a valid XAB, RMS-11l returns the error 
code ERSXAB. 


5.4.3.2 Input Values - The NXT field must contain either: 
e zero (0) = there are no more XABS in this chain 


e address of an Extended Attribute Block separately allocated in the 
program 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


5.4.3.3 Initialization and Default - Macro takes the form: 


XSNXT label 


If there is no initialization macro, NXT = 0. 
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5.4.4 PRG 


The one-word Programmer Number (PRG) field contains the second number 
in the file owner's account number pair. 


5.4.4.1 Use 
Input to: 
SCLOSE/SCREATE 
You set the PRG field to the individually unique number of 
the owner of the file. 
Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the PRG field to the individually unique number 
of the file owner it reads from the file directory. 


5.4.4.2 Input Values 


MINIMUM = 0, meaning the default programmer number, based on the ac- 
count in which the program is currently running 
= 1, the smallest programmer number you can identify 
MAXIMUM = 255 


The programmer number specified in the Protection XAB must agree with 
the programmer number specified in the filespec indicated by the FAB 
FNA field or in the default name string indicated by the FAB DNA 
field. 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (see Chapter 7). 


5.4.4.3 Initialization and Default - Macro takes the form: 


XSPRG numeric 


If there is no initialization macro, PRG = 0. 
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5.4.5 PRJ 


The one-word Project Number (PRJ) field contains the first number in 
the file owner's account number pair. 


5.4.5.1 Use 
Input to: 
$C LOSE/S$CREATE 
You set the PRJ field to the group or project number of the 
owner of the file. 
Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the PRJ field to the group or project number of 
the file owner it reads from the file header. 


5.4.5.2 Input Values 


MINIMUM 


0, meaning the default project number, based on the account 
in which the program is currently running 


1, the smallest project number you can identify 

MAXIMUM = 255 

The project number specified in the Protection XAB must agree with the 
project number specified in the filespec indicated by the FAB FNA 
field or in the default name string indicated by the FAB DNA field. 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (See Chapter 7). 


5.4.5.3 Initialization and Default - Macro takes the form: 


XSPRJ numeric 


If there is no initialization macro, PRJ = 0. 
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5.4.6 PRO 


The one-word System File Protection Code (PRO) field contains the sys- 
tem-specific code that indicates the access relationship allowed for 
the file represented by the FAB linked to this XAB. 


5.4.6.1 Use 
Input to: 
SCREATE 
You set the PRO field to the protection code that controls 
access to the file as you want it. 
Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the PRO field equal to the protection code found 
in the file directory. 


5.4.6.2 Input Values - Specific protection values depend on operating 
system standards: 


@ IAS/RSX-11M 


The file protection value identifies the file access privileges of 
four classes of users: 


group those accounts with the project number contained in 
the PRJ field of this XAB 


owner that account with the project and programmer numbers 
contained in this XAB 


system privileged accounts 
world all accounts not in the other categories 


The PRO field assumes the following format: 
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Each of the categories is allocated four bits, with the following 
meanings with respect to file access: 


If a bit is not set (zero), the respective type of access to. the 
file is allowed; if the bit is set (one), that type of access is 
denied. 


You should use a numeric value for that PRO field that sets the ap- 


propriate bits; this number may be decimal, octal, or binary, 
though using the MACRO-11 octal radix unary operator makes it ea- 
sier. 

e RSTS/E 


The file protection value identifies the file access privileges of 
three classes of users: 


group those accounts with the project number contained in 
the PRJ field of this XAB 


owner that account with the project and programmer numbers 
contained in this XAB 


others all accounts not in the owner or group categories 


The value of the PRO field is the numeric sum of one or more of the 
following codes: 


1 read protect against owner 
2 write protect against owner 
4 read protect against everyone in group except owner 
8 write protect against everyone in group except owner 
16 read protect against others 
32 write protect against others 
See also your operating system documentation about protection codes. 


A value can be set in the field with the initialization macro shown 
below or with the $STORE field access macro (see Chapter 7). 


5.4.6.3 Initialization and Default - Macro takes the form: 
XSPRO numeric 


If there is no initialization macro, PRO = 0. 


Protection XAB: PRO 5-71 


5.5 Summary Extended Attribute Block 


The Summary XAB generally describes an Indexed file, including’ the 
number of keys and areas established for the file when it was created. 
Summary XABS may also be used for Relative files if you want to deter- 
mine their prologue version number. 


Summary XABS are used as output only during SDISPLAY and SOPEN' opera- 
tions. 


Example You want to open an Indexed file, but you don't know any- 
thing about its keys or areas, including their number. You 
therefore do not know how many Key or Allocation XABs_ to 
link to the FAB before you issue the SOPEN macro. You can, 
however, link a Summary XAB to the FAB and initiate an open 
operation. You then examine the NOA and NOK fields of the 
Summary XAB to determine how many of the other XABsS you need 
for a S$DISPLAY macro. 


Table 5-5: Summary Extended Attribute Block Fields 


Field | Field 
Name Size 













Default Description 










SUM XAB length 
XAB type 
Number of areas 
Number of keys 

Next XAB 

RMS-11 Prologue version number 
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5.5.1 BLN 


The XABSB macro sets the one-byte Block Length (BLN) field to the Ex- 
tended Attribute Block length. 
CAUTION 


DO NOT CHANGE THE BLN FIELD. 


5.5.1.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 


the BLN field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ERSBLN error code, 
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5.5.2 COD 
The XABS$B macro sets the one-byte Code (COD) field to the Extended At- 
tribute Block type, with the symbolic value of XBSSUM. 

CAUTION 


DO NOT CHANGE THE COD FIELD. 


5.5.2.1 Use - Before RMS-11 uses an XAB during a file operation, it 
verifies that the block is a valid XAB; one of the checks examines 
the COD field. If this field does not contain the proper code, RMS-11 
aborts the operation with a ERSCOD error code. 
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5.5.3 NOA 


The one-byte Number Of Areas (NOA) field contains the number of file 
areas that were created in the file represented by the linked FAB. 


5.5.3.1 Use - The NOA field is only applicable to Indexed files. 
Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the NOA file equal to the number of areas in the 
file associated with the XAB. 


5.5.3.2 Output Values 


MINIMUM 


1 


MAXIMUM 


254 
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5.5.4 NOK 


The one-byte Number Of Keys (NOK) field contains the number of keys 
that were created in the file represented by the linked FAB. 


5.5.4.1 Use - The NOK field is only applicable to Indexed files. 
Output from: 
SDISPLAY/SOPEN 


RMS-11 sets the NOK file equal to the number of keys in the 
file associated with the XAB. 


5.5.4.2 Output Values 
MINIMUM = 0, meaning a Relative file 


1, minimum number of keys for an Indexed file 


i] 


MAXIMUM 255 
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5.5.5 NXT 
The one-word Next XAB (NXT) field, if not zero, points to another sep- 


arately allocated XAB and thereby indicates to RMS-1ll that there is at 
least one more XAB in the chain connected to the FAB via the FAB’ XAB 


field. See Chapter 1 at the beginning of this chapter. 


5.5.5.1 Use 
Input to: 
SCREATE/SDELETE/S$EXTEND/SOPEN 


e If you have allocated another XAB and want RMS-11 to use 
it, you set the NXT field equal to the address of that 
XAB. 

e If you have not allocated an XAB and/or you want the XAB 
chain to end here, set the NXT field equal to zero; 
otherwise, RMS-11 interprets the value in the field as an 
address and tries to use the area indicated as an XAB: 


if that area is not a valid XAB, RMS-11 returns the error 
code ERSXAB. 


5.5.5.2 Input Values - The NXT field must contain either: 
e zero (Q) = there are no more XABs in this chain 


e address of an Extended Attribute Block separately allocated in the 
program 


A value can be set in the field with the initialization macro shown 
below or with the SSTORE field access macro (See Chapter 7). 


5.5.5.3 Initialization and Default - Macro takes the form: 


XSNXT label 


If there is no initialization macro, NXT = 0. 
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5.5.6 PVN 


The one-word Prologue Version Number (PVN) field contains the RMS-11 
Prologue version number. 


5.5.6.1 Use - The PVN field is only applicable to Relative and In- 
dexed files. 


Output from: 
SDISPLAY/SOPEN 
RMS-11 sets the PVN field equal to the version number it 


finds in the file Prologue, if the Summary XAB is long 
enough to contain this field (see "Comments"). 


5.5.6.2 Output Values - 


MINIMUM 


1, for Relative files and Indexed files with string keys 


MAXIMUM = 2, for Indexed files with nonstring keys 


5.5.6.3 Comments - RMS-11 fills in the PVN field if the Summary XAB 
is long enough to contain it. The XAB won't be long enough if you as- 
sembled your program using RMS-11 V1.0 RMSLIB.MAC and then task built 
it using RMS-1l V1.5 RMSLIB.OLB. 
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CHAPTER 6 


NAME BLOCK 


The initialization macros (this chapter) and the field access macros 
(Chapter 7) are provided so that you do not have to know the specific 
position and to a large extent, the size of each field in a NAM Block. 
You can, therefore, treat the fields as logical entities. It is also 
possible that the positions and sizes of the fields will change from 
release to release of RMS-11l. 


However, you can determine the position of any field in a NAM as an 
offset from the NAM's starting address. RMS-1ll represents these off- 
set values with symbols in following form: 


OSfnm 


where fnm is the three-letter name of a NAM Block field; fnm is’ the 
name used to reference the field in the initialization and field ac- 
cess macros. 


Example OSESA for the expanded string address field 


The values of these symbols can be found in the symbol table of an as- 
sembly listing file for any module containing the FAB. 


Table 6-1: NAM Block Fields 


Field | Field Default Description 
Name Size 


1W Device ID 

Expanded string address 
Expanded string length 
Expanded string size 
File ID 
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6.1 DVI 


The three-word Device ID (DVI) field contains a code that the file 
processor can use in conjunction with a file ID to locate a file with- 
out consulting device directories. 


6.1.1 Use 


Input to: 


SERASE/SOPEN 
You set the NAM DVI field equal to a device ID value RMS-11l 
provided during a previous create or open by file specifica- 
tion operation. You must also set the NAM FID field equal 
to the file ID returned during the same operation as well as 
storing FBSFID in the FAB FOP field. 


Output from: 
SCREATE/SOPEN by file specification 


RMS-11 sets the DVI field equal to the code the file proces- 
sor provides during the open by file specification process. 


6.1.2 Input Values 


You should make no attempt to analyze or change the device ID provided 
by RMS-ll. Store the contents of the NAM DVI field as a three-word 
quantity and supply it as such when you execute an erase or open by 
file ID operation. 
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6.2 ESA 
The Expanded String Address (ESA) field contains the address of a 
buffer that you have allocated. During an open, create, or erase op- 
eration, RMS-1l places in this buffer the file specification string 
resulting from the application of default information (provided by the 
default name string of the FAB and system defaults) to the primary 
file name string of the FAB. 
The ESA buffer must be present if the FAB NAM field is not zero. 

NOTE 


The NAM ESA field and the expanded string buffer are not re- 
quired or used during an open or erase by file ID operation. 


6.2.1 Use 


Input to SCREATE/SERASE/SOPEN: 
You set the ESA field equal to the address of a buffer where you 
want RMS-1l1l to store the full file specification. 


6.2.2 Input Values 
ESA must contain either: 


e zero (0) = there is no file specification buffer for this 
operation; valid only for open and erase by file ID 


e address of the first byte of a buffer for the full file specifica- 
tion; the buffer does not have to be word-aligned 


A value can be set in the field with the initialization macro shown 
below or with the S$STORE field access macro (see Chapter 7). 


6.2.3 Initialization and Default 
Macro takes the form: 
NSESA address 


If there is no initialization macro, BKS = 0. 
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6.3 ESL 
The one-byte Expanded String Length (ESL) field contains the actual 


length of the full file specification RMS-11l stored beginning with the 
address in the NAM ESA field. 


6.3.1 Use 


Output from: 
SCREATE/SERASE/SOPEN by file specification 


RMS-11 sets the ESL field equal to the size in bytes of the 
expanded file specification resulting from the operation. 
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6.4 ESS 


The one-byte Expanded String Size (ESS) field contains the size of the 


buffer whose address you stored in the NAM ESA field. 


6.4.1 Use 


Input to: 
SCREATE/SERASE/SOPEN 


You set the ESS field equal to the size of the buffer 
you want RMS-11 to store the full file specification. 


6.4.2 Input Values 
MINIMUM = 1 
MAXIMUM = 255 


A value can be set in the field with the initialization macro 
below or with the SSTORE field access macro (see Chapter 7). 


6.4.3 Initialization and Default 
Macro takes the form: 
NSESS numeric 


If there is no initialization macro, ESS = 0. 


NAM Block (NAM): ESS 


where 


shown 
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6.5 FID 


The three-word File ID (FID) field contains a code that the file  pro- 
cessor can use in conjunction with a device ID to locate a file with- 
out consulting device directories. 


6.5.1 Use 


Input to: 


SERASE/SOPEN 
You set the NAM FID field equal to a file ID value RMS-11 
provided during a previous create or open by file specifica- 
tion operation. You must also set the NAM DVI field equal 
to the device ID returned during the same operation as well 
as storing FBSFID in the FAB FOP field. 


Output from: 


SCREATE/SOPEN by file specification 
RMS-11 sets the FID field equal to the index the file  pro- 
cessor provides during the open by file specification pro- 
cess. 


6.5.2 Input Values 


You should make no attempt to analyze or change the File ID provided 
by RMS-1l1. Store the contents of the NAM FID field as a three-word 
quantity and supply it as such when you execute an erase or open by 
file ID operation. 
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CHAPTER 7 


FIELD ACCESS MACROS 


RMS-11 field access macro retrieve, modify, and test the contents of 
fields in the RMS-11 control blocks, FABs, RABS, and XABs, at run 
time. These macros enable you to treat the control block fields as 
logical entities, without regard for the placement of the fields with- 
in the control blocks and to a large degree, for the sizes of the 
fields. 


Table 7-1 contains a summary of the available macros. Each macro is 
also described in a separate section of this chapter. 


RMS-11 assumes octal radix for all numeric values used as operands for 
the field access macros. 


In all two-word fields containing numeric values, the least’ signifi- 


cant bits appear in the word with the lower address. 


Table 7-1: RMS-11 Field Access Macros 


SCOMPARE 1 byte or 1 word Compares the contents of a field 
with a value you specify. 


SFETCH Any size Copies the contents of a field into 
a location you specify. 


SOFF 1 byte or 1 word Resets one or more bits within a 
bit string field. 


SSET 1 byte or 1 word Sets one or more bits within a bit 
String field. 


SSTORE Any size Copies the contents of a _ location 
you specify into a field. 


STESTBITS 1 byte or 1 word Tests one or more bits within a bit 
string field. 
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7.1  SCOMPARE 


The SCOMPARE macro compares a one-byte or one-word control block data 
field with a value you specify and sets the PDP-11 condition codes. 


7.1.1 General Form 
SCOMPARE source,fnm,reg 


where source represents a value you want compared with the contents of 
a control block data field. You can express this operand 
using any valid addressing mode. The operand must be 
word-aligned for comparison with one-word data fields. 


fnm is the three-letter name of a one-byte or one-word field. 
The assembler generates an error message if the name is 
invalid for the block referenced by reg or if the field 
specified by fnm is a multiword field. 


reg is a general register (RO through R5) loaded with the ad- 
dress of the control block containing the specified 
field. 


7.1.2 Effect 


The SCOMPARE macro makes the syntax checks as described under "General 
Form." Then, if the source operand is #0, the macro generates a TST or 
TSTB instruction, according to the size of the field. If the source 
operand is not #0, the macro generates a CMP or CMPB instruction ap- 
propriately, comparing the source operand with the specified field as 
an offset from the contents of the specified register. 


At run time, condition codes are set according to the instruction gen- 
erated. 


7.1.3 Examples 
e@ SCOMPARE #SUSSUC,STS,R1 


The contents of the STS field in the control block pointed to by Rl 
are compared with the symbolic completion value SUSSUC. 
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SCOMPARE 2(R1),RSZ,R5 


The contents of the Record Size field in the RAB indicated by R5 is 
compared with the operand specified by indexed addressing mode. 


SCOMPARE #0,STS,R1 


BGT 14$ ; CONTINUE IF SUCCESSFUL 
BLT ERRTN ; HANDLE ERROR IF THERE IS ONE 
JMP TRUBLE ; SOFTWARE IS IN A JAM 


General register Rl points to the block controlling the operation 
just completed (FAB for file operations, RAB for record opera- 


tions). The program then branches according to the contents of the 
STS field. 
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7.2 SFETCH 


The SFETCH macro copies the contents of a control block data _ field 
into a location you specify. This macro can be used to access a field 
of any size. 


7.2.1 General Form 
SFETCH destination,fnm,reg 


where destination is a location within your program where you want the 
contents of a control block field copied. The fol- 
lowing restrictions apply to this operand: 


e You cannot use immediate mode or any form of de- 
ferred addressing mode: the assembler generates 
an error. 


e If fnm is POS or SIZ, you cannot use register 
mode addressing: the assembler generates an 
error. 


e For multiword fields other than POS or SIZ, use 
register mode addressing carefully: the $FETCH 
Macro uses successive registers as destination 
operands for successive words of the data field; 
it uses the register containing the control block 
address if the data field is long enough. The 
results are unpredictable. 


e For single- and multiword fields, the destination 
location must be word-aligned. 


fnm is the three-letter name of any field within the 
control block. The assembler generates an error if 
the name is invalid for the block referenced by reg. 


To reference Key XAB SIZ and POS fields, you: 


e specify SIZ or POS to fetch all eight words of 
the field. The macro copies the words into suc- 
cessive locations beginning with the destination 
you specify. 


e specify SIZ or POS plus a number from 0 through 7 


to fetch a single word from the field. See "Ex- 
amples." 


7-4 Field Access Macros: SFETCH 


reg is a general register (RO through R5) loaded with 
the address of the control block containing the 
source data field. 


7.2.2 Effect 
The S$FETCH macro makes the syntax checks as described under "General 


Form." Then, the macro generates a MOVB or one or more MOV instruc- 
tions, according to size of the field. 


7.2.3 Examples 
e SFETCH R2,RBF,R4 


General register R4 contains the address of a RAB. The macro co- 
pies the contents of that RAB's RBF field into general register R2. 


e SFETCH 8.(R3),MRN,R1 
General register Rl contains the address of a FAB. The macro co- 
pies both words of that FAB's MRN field into successive words be- 
ginning with the specified location. 

e S$FETCH LSEG3,S1Z2,R5 
General register R5 contains the address of a Key XAB. The macro 


copies the length of the third key segment into the location la- 
beled LSEG3. 
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7.3 SOFF 


The SOFF macro resets one or more bits within a one-byte or one-word 
bit string data field. 


7.3.1 General Form 
SOFF value,fnm,reg 


where value is an expression or location specifying the bits within 
the data field you want reset, 


fnm is the three-letter name of a one-byte or one-word field. 
The assembler generates an error message if the name is 
invalid for the block referenced by reg or if the field 
specified by fnm is a multiword field. 


reg is a general register (RO through R5) loaded with the ad- 
dress of the control block containing the specified field. 


7.3.2 Effect 
The S$OFF macro makes the syntax checks as described under "General 


Form." Then, the macro generates one or more BIC or BICB instructions, 
according to size of the field. 


7.3.3 Examples 
e SOFF RBSKGE, ROP, R2 
General register R2 contains the address of a RAB. The macro oper- 


ates on that RAB's ROP field, resetting the bit that specifies gre- 
ater than or equal key match during a random record operation. 


7.3.4 Comments 
The SOFF macro resets individual bits. You should use the SSTORE 


macro instead if you want to clear an entire bit string field or reset 
a value ina field not a bit string. 
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7.4 SSET 


The SSET macro sets one or more bits within a one-byte or one-word bit 
string data field. 


7.4.1 General Form 
SSET value,fnm,reg 


where value is an expression or location specifying the bits within 
the data field you want set, 


fnm is the three-letter name of a one-byte or one-word field. 
The assembler generates an error message if the name is 
invalid for the block referenced by reg or if the field 
specified by fnm is a multiword field. 


reg is a general register (RO through R5) loaded with the ad- 


dress of the control block containing the specified data 
field. 


7.4.2 Effect 
The SOFF macro makes the syntax checks as described under "General 


Form." Then, the macro generates one or more BIS or BISB instructions, 
according to size of the field. 


7.4.3 Examples 

e SSET FBSGET! FBSUPD,FAC,R4 
General register R4 contains the address of a FAB. The macro’ sets 
bits within that FAB's FAC field indicating get and update opera- 


tions will be performed on the associated file. The S$SET macro is 
executed before a SCREATE or SOPEN operation is initiated. 


e SSET RBSEOF,ROP,R1 
General register Rl contains the address of a RAB. The macro” sets 


the bit within that RAB's ROP field that specifies positioning to 
end-of-file during the following SCONNECT record operation. 
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7.4.4 Comments 


The SSET macro sets individual bits. You should the SSTORE macro 
instead if you want to: 


e set only the specified values in a bit string field, ensuring that 
no other bits remain set 


e set a value in a field not a bit string S$STORE macro. 
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7.5 SSTORE 


The $STORE macro copies values from a location you specify into a con- 
trol block data field. This macro can be used to access a field of 
any size. 


7.5.1 General Form 
SSTORE source,fnm,reg 


where source represents a value or series of values you want stored in 
a control block data field. The following restrictions 
apply to this operand: 


e You cannot use any form of deferred addressing mode: 
the assembler generates an error. 


e Immediate mode addressing can be used only with 
one-byte and one-word fields: the assembler generates 
an error. 


e If fnm is POS or SIZ, you cannot use register mode ad- 
dressing: the assembler generates an error. 


e For multiword fields other than POS or SIZ, use regis- 
ter mode addressing carefully: the SSTORE macro uses 
successive registers as source operands for successive 
words of the data field; it uses the register con- 
taining the control block address if the data field is 
long enough. The results are unpredictable. 


e For single- and multiword fields, the source location 
must be word-aligned. 


fnm is the three-letter name of any field within the control 
block. The macro changes all bytes in this field. The 
assembler generates an error if the name is invalid for 
the block referenced by reg. 
To reference Key XAB SIZ and POS fields, you: 


e specify SIZ or POS to change all eight words of the 


field. The macro copies eight words from successive 
locations beginning with the source location you spec- 
ify. 
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e specify SIZ or POS plus a number from 0 through 7 to 
store a Single word into the field. See "Examples." 


reg is a general register (RO through R5) loaded with the ad- 


dress of the control block containing the source data 
field. 


7.5.2 Effect 

The SSTORE macro makes the syntax checks as described under "General 
Form." Then, the macro generates a MOVB or one or more MOV instruc-— 
tions, according to size of the field. For multiword fields, the 
macro generates a MOV instruction for each word in the field, begin- 


ning with the specified source location and using successive words 
after that. 


7.5.3 Examples 
e SSTORE 0,ALQ,R3 


General register R3 contains the address of a FAB. The macro 
clears that FAB's two-word ALO field. 


e SSTORE INPUT, FAB,R1 


General register Rl contains the address of a _ RAB. The macro 
stores the address of a FAB in that RAB's FAB field. 


e SSTORE 23.,S1Z2,Rl 


General register Rl points to a Key XAB. The macro changes’ the 
size of the third segment of the key defined by the XAB. 
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7.6 S$TESTBITS 


The STESTBITS macro compares one or more bits within a one-byte or 
one-word control block data field with a value you specify and sets 
the PDP-11 condition codes. 


7.6.1 General Form 
STESTBITS value,fnm,reg 


where value is an expression or location specifying the bits within 
the data field you want tested, 


fnm is the three-letter name of a one-byte or one-word field 
within a control block. The assembler generates an error 
message if the name is invalid for the block referenced by 
reg or if the field specified by fnm is a multiword field. 


reg is a general register (RO through R5) loaded with the ad- 


dress of the control block containing the specified data 
field. 


7.6.2 Effect 
The SOFF macro makes the syntax checks as described under "General 


Form." Then, the macro generates one or more BIT or BITB instructions, 
according to size of the field. 


7.6.3 Examples 
STESTBITS FBSUPD!FBSPUT,FAC,R3 
General register R3 contains the address of a_ FAB. The macro 
checks that FAB's FAC field to determine if the current program can 


issue update or put operations. If either or both bits are _ set, 
condition code Z is not set; if neither is set, code Z is set. 
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CHAPTER 8 


FILE AND RECORD OPERATION MACROS 


8.1 FILE OPERATION MACROS 


A file operation macro causes RMS-11 to perform an action related to 
an entire file. The macro name indicates the type of operation per- 
formed. The fields of the FAB associated with the macro in the cal- 
ling sequence identifies the file and qualifies the operation. 


Table 8-1 summarizes the RMS-11 file operation macros. 


Table 8-1: RMS-11 File Operation Macros 


Macro Name Description 


SCLOSE Closes an open RMS-11 file so that your program can no 
longer access its contents. 


SCREATE RMS-11 creates and opens an RMS-11 file as described by 
the associated FAB and XABs, if any. 


SDISPLAY Stores attributes of an existing RMS-11 file in FAB and 
XAB fields. 


SERASE Deletes an existing RMS-11 file and removes its entry(s) 
from a directory. 


SEXTEND Increases the number of blocks allocated to an RMS-1l1 
file. 


SOPEN Opens an existing RMS-11 file, making its contents ava- 
ilable for processing. 
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8.1.1 SCLOSE 


The $CLOSE macro closes an open RMS-11 file, making its contents’ una- 
vailable to your program. The operation effectively disconnects all 
the file's Record Access Streams; if a stream has an outstanding I/0 
request, the close fails with the ERSACT error code. However, you 
should shut down all streams with SDISCONNECT macros before initiating 
a close operation. 


8.1.1.1 Buffer Requirements - One BDB and 512 bytes of I/0 buffer 
space. 


NOTE 
Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 


operation are typically met without specific attention on 
your part. 


8.1.1.2 Input Fields - 


FAB FOP (can contain FBSRWC to rewind a magtape file) 
IFI 


PRO XAB All fields 


8.1.1.3 Output Fields - 


FAB IFI (set to zero) 
BPA (address of buffer area returned for your use) 
BPS (size of buffer area returned for your use) 
STS 
STV 


8-2 File Operation Macros: SCLOSE 


SCLOSE fab[,error] 


where fab is the address of a File Access Block representing an open 


RMS-11 file. 


error is the address of a completion routine to be called if the 
SCLOSE operation fails. 


8.1.1.5 Comments - 


Even if RMS-11 returns the ERSWER error code in the FAB STS field, 
the file is closed and deaccessed. 


If you issue a record operation on a file after it is closed, 
RMS-11 returns error code ERSISI. 


If your program operates as follows, be sure to detach the NAM 
Block before initiating the $CLOSE macro: RMS-11 destroys the NAM 
FID field during close. 


1. Program links NAM Block to FAB, then opens file by file specif- 
ication. 


2. Program closes file. 


3. Program opens or erases file by file ID. 
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8.1.2 SCREATE 


The SCREATE macro creates an RMS-1l file with the attributes you spec- 
ify in a FAB and any XABs linked to that FAB, then makes the new files 
available for processing by your program, 


Key and Allocation XABs must be grouped in densely ascending order 
(see Section 5.0.3); otherwise, RMS-11 returns the error code ERSORD. 
An illogical XAB type in the chain causes the ERSCOD error code. 


Example Summary XAB. 

Example Key XAB for a Sequential file. 

If no Allocation XABs are linked to the FAB, the create operation cre- 
ates the file as a single area (Area 0), using data from the FAB 
fields to control its processing. 

However, if one or more Allocation XABs are linked to the FAB, the 
create operation ignores the FAB ALQ and BKS fields, creating the file 
according to the values in the ALL XAB(s), establishing areas as spec- 
ified. 


If a NAM Block is linked to the PAB, RMS-1l1l provides the expanded file 
specification of the new file. 


The new file must be closed before your program terminates. 


8.1.2.1 Buffer Requirements - One BDB and 512 bytes of I/0 buffer 
space. 


NOTE 


Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 
operation are typically met without specific attention on 
your part. 


8-4 File Operation Macros: SCREATE 


8.1.2.2 


FAB 


ALL XAB 
KEY XAB 


PRO XAB 


8.1.2.3 


FAB 


NAM 


Input Fields - 


ALQ 
BKS 
BLS 
BPA 
BPS 
DEQ 
DNA 
DNS 
FAC 
FNA 
FNS 
FOP 
FSZ 
LCH 
MRN 
MRS 
NAM 
ORG 
RAT 
RFM 
RTV 
SHR 
XAB 


All 
All 


All 


(ignored if Allocation XABs linked) 
(ignored if Allocation XABs linked) 
(magnetic tape files only) 


(used when no ALL XABS or ALL XAB DEQ field is zero) 


(must contain at least FBSPUT) 


(VFC records only) 


(Relative files only) 


fields 
fields 


fields 


Output Fields - 


DEV 
IFI 
STS 
STV 


DVI 
ESA 
ESL 
FID 


8.1.2.4 General Form - 


SCREATE 


where rab 


error 


rab[,error] 


is the address of a Record Access Block representing a 


cord Access Stream. 


is the address of a completion routine to be called if 


SCREATE operation fails. 
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8.1.3 SDISPLAY 


The SDISPLAY macro causes RMS-11l to store attribute information from 
an open file in XAB fields. 


Key and Allocation XABs must be grouped in ascending order (error code 


ERSORD), but they do not have to be densely ordered. RMS-11 ignores 
excess and illogical XABs. 


8.1.3.1 Buffer Requirements ~- One BDB and 512 bytes of I/0 buffer 
space, 
NOTE 
Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 


operation are typically met without specific attention on 
your part. 


8.1.3.2 Input Fields - 


FAB IFI 
XAB 


ALL XAB AID 
NXT 


DAT XAB NXT 
KEY XAB NXT 
PRO XAB NXT 


SUM XAB NXT 
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8.1 


ALL 


DAT 
KEY 
PRO 


SUM 


8.1 


whe 


8.1 


3.3 Output Fields - 


FAB STS 
STV 


XAB ALN 
ALQ (number of blocks unused in current extent) 
AOP (can contain XBSCTG) 
BKZ 
DEQ 
LOC 
XAB All fields 
XAB All fields 
XAB All fields 
XAB All fields 


NAM All fields 


3.4 General Form - 
SDISPLAY fab[,error] 


re fab is the address of a File Access Block representing an exist- 
ing RMS-1ll file. 


error is the address of a completion routine to be called if the 
SDISPLAY operation fails. 


-3.5 Examples - 


A program that opens a file with unknown attributes cannot link in 
the proper Key and Allocation XABs. That program can link a Summa- 
ry XAB to the FAB, then open the file. From the SUM XAB, the pro- 
gram determines whether XABs are appropriate, then how many of each 
are necessary. The program links in the proper XABs and executes a 
SDISPLAY macro to obtain the attribute information. 


A program has room for only one XAB. It can accumulate the infor- 


Mation it needs on areas and keys by executing a series of SDISPLAY 
macros, changing the XAB fields appropriately between operations. 


File Operation Macros: SDISPLAY 8-7 


REKKKEKKKKEKKRKEESK 


* * 
* SERASE * 
* * 
KRREKKKEKKKKRKEKRKEKEE 


8.1.4 SERASE 

The SERASE macro deletes an RMS-11 file and removes its directory 
entry(s). The blocks occupied by the file are made available for 
reuse in other files. 

You can erase a file by file specification or by file ID. You indi- 
cate the file specification in a FAB. To specify a file by file ID, 
you must: 

e link a NAM Block to the FAB 

e indicate the correct ID with the NAM FID field 

e set the value FBSFID in the FAB FOP field 


e set appropriate values in the other input fields (see "Input 
Fields") 


If the file is open, your program cannot erase it on the logical chan- 
nel it was opened on. 


Example A file is opened with the FAB LCH field set to 3. Channel 3 
cannot be used for any other file operation, including 
erase, until that file is closed. 


You cannot erase magnetic tape files or files on unit record devices. 


8.1.4.1 Buffer Requirements - One BDB and 512 bytes of I/0 buffer 
space. 


NOTE 
Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 


operation are typically met without specific attention on 
your part. 


8-8 File Operation Macros: S$ERASE 


8.1.4.2 Input Fields - 


FAB BPA 
BPS 
DNA 
DNS 
FNA 
FNS 
LCH (must be different from open LCH) 
NAM 


NAM DVI 


ESS 
FID 


8.1.4.3 Output Fields - 


FAB STS 
STV 


8.1.4.4 General Form - 
SERASE fab[,error] 


where fab is the address of a File Access Block representing an exist- 
ing RMS~-11 file. 


error is the address of a completion routine to be called if the 
SERASE operation fails. 


8.1.4.5 Comments - If your or another program has a file open and 
your program erases the file (on a different logical channel), the 
file processor does not delete the file from the directory and release 
its allocated blocks until all accessors close the file. 
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8.1.5 SEXTEND 


The SEXTEND macro requests the file processor to add blocks to a 
file's allocation. 


If no Allocation XABs are linked to the FAB, RMS-11 extends Area 0O*, 
using data from the FAB fields to control its processing. If the FAB 
FOP field contains FBSCTG, RMS-1l1 requests the file processor to allo- 
cate the requested blocks contiguously with those blocks already allo- 
cated to the file; if no contiguous blocks are available, RMS-1l_ re- 
turns an error. 


However, if one or more Allocation XABs are linked to the FAB, RMS-11 
extends the areas indicated by the ALL XAB AID fields by the amounts 
specified in the ALL XAB ALQ fields. If the XAB AOP field contains 
XBSCTG, RMS-11 requests the file processor to allocate the requested 
blocks contiguously with those blocks already allocated to the area; 
if no contiguous blocks are available, RMS-11l returns an error.} 


8.1.5.1 Buffer Requirements - One BDB and 512 bytes of I/0 buffer 
space. 


NOTE 


Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 
operation are typically met without specific attention on 
your part. 


8.1.5.2 Input Fields - 


FAB ALQ (ignored if Allocation XABs linked) 
FOP (can contain FBSCTG; ignored if Allocation XABs linked) 
IFI 
XAB 


ALL XAB AID 
ALQ 
AOP (can contain XBSCTG) 


*For Sequential and Relative files, Area 0 is the file. 
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8.1.5.3 Output Fields - 


FAB ALQ (number of blocks actually added to the file) 
STS 
STV 


ALL XAB ALQ (number of blocks actually added to the file) 


8.1.5.4 General Form - 


SEXTEND rab[,error] 


where rab is the address of a Record Access Block representing a Re- 


cord Access Stream. 


error is the address of a completion routine to be called if the 
SEXTEND operation fails. 


8.1.5.5 Comments - RMS-1l applies the following restrictions to’ the 
erase operation: 


The file must be open. 


All Record Access Streams connected to the file must be inactive; 
otherwise, RMS-1l returns error code ERSACT. 


The file must have been opened with at least one of the _ following 
specified in the FAB FAC field: 


FBSDEL 
FBSPUT 
FBSUPD 


The file does not reside on magnetic tape; otherwise, RMS-1ll_ re- 
turns error code ERSIOP. 
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8.1.6 SOPEN 


The SOPEN macro makes an existing RMS-11 file available for processing 
by your program. RMS-11 also returns the basic attributes of the file 
in the FAB associated with the macro; if XABs are linked to the’ FAB, 
RMS-11 files in attribute information appropriately; and if a NAM 
Block is linked, RMS-11 provides the expanded file specification of 
the open file. 


Key and Allocation XABs must be grouped in ascending order (error code 
ERSORD), but they do not have to be densely ordered. RMS-11 ignores 
excess and illogical XABs. 


You can open a file by file specification or by file ID. You indicate 
the file specification ina FAB. To specify a file by file ID, you 
must: 


e link a NAM Block to the FAB 
e indicate the correct ID with the NAM FID field 
e set the value FBSFID in the FAB FOP field 


@e set appropriate values in the other input fields (see "Input 
Fields") 


8.1.6.1 Buffer Requirements - One BDB and 512 bytes of I/0 buffer 
space. 


NOTE 
Since any record operation requires at least one BDB and an 
I/O buffer a block long, the buffer requirements for this 


operation are typically met without specific attention on 
your part. 
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8.1.6.2 


FAB 


ALL XAB 


DAT XAB 
PRO XAB 
SUM XAB 


NAM 


8.1.6.3 


FAB 


ALL XAB 


Input Fields - 


BPA 
BPS 
DEQ 
DNA 
DNS 
FAC 
FNA 
FNS 
FOP 
LCH 
NAM 
RTV 
SHR 
XAB 


AID 
DEQ 
NXT 
NXT 
NXT 
NXT 
DVI 


ESS 
FID 


(used as temporary run-time value) 


Output Fields - 


ALQ 
BKS 
DEQ 
BLS 
DEV 
FOP 
FSZ 
IFI 
MRN 
MRS 
ORG 
RAT 
RFM 
RTV 
STS 
STV 


ALN 
ALQ 
AOP 


(if input value = 0, Set to value set at create time) 
(magnetic tape files only) 


(contains FBSCTG if the file is contiguous) 
(VFC records only) 


(Relative files only) 


(number of blocks unused in current extent) 
(can contain XBSCTG) 
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BKZ 

DEQ 

LOC 
DAT XAB All fields 
PRO XAB All fields 
SUM XAB All fields 


NAM All fields 


8.1.6.4 General Form - 
SOPEN fab[,error] 


where fab is the address of a File Access Block representing an exist- 
ing file. 


error is the address of a completion routine to be called if the 
SOPEN operation fails. 


8.1.6.5 Comments - If you intend to extend the file while it is open, 
ensure that the FAB FAC field contains FBSDEL, FBSPUT, and/or FBSUPD 
before your program initiates the open operation. 
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8.2 RECORD OPERATION MACROS 
After it has created or opened an RMS-11 file, your program can _ per- 
form record operations on it. These operations involve the following 
concepts that are explained in the RMS-11 User's Guide and Chapter 1 
of this manual. 

Record Access Streams 

File sharing 


Context, Current Record, and Next Record 
Synchronous and asynchronous record operations 


Table 8-2: RMS-11 Record Operation Macros 
SCONNECT Establishes a Record Access Stream. 


SDELETE Deletes a record from an RMS-11 Relative or Indexed 
file. 


SDISCONNECT Terminates a Record Access Stream. 

SFIND Locates a record in an RMS-1l file. 

SF LUSH Moves all data in unwritten I/0 buffers to disk. 
SFREE Unlocks a bucket locked by a Record Access Stream. 


SGET Moves a record from an RMS-11 file into your program's| 
user buffer. 


SNXTVOL Continues processing with the next volume of magnetic 
tape multivolume set. 


SPUT Moves a record from your program's user buffer 
RMS-11 file. 


SREWIND Resets a Record Access Stream's context to the logical 
beginning of an RMS-11 file. 


STRUNCATE Deletes record at the end of an RMS-11 Sequential 
file. 


SUPDATE Replaces a record in an RMS-11 file with a record from 
your program's user buffer, 


SWAIT Suspends processing until an RMS-11 asynchronous” re- 
cord operation completes. 





Record Operation Macros 8-15 


REEKKKEKKKRKEKKKKK 


*k * 
* SCONNECT * 
* * 
KAKKKKKKRKKRKRKRKKEK 


8.2.1 S$CONNECT 


The SCONNECT macro establishes a Record Access Stream by associating a 
RAB with a FAB. RMS-11 also allocates buffer space or uses the GSA 
routine you provided to allocate buffer space, for: 


e internal control structures from the central buffer pool 


e I/0 buffers from the central or private pool as you indicate in the 
FAB, according to file organization and the values specified in RAB 
MBC and MBF fields 


8.2.1.1 Input RAB Fields - 


BID 

BLN 

FAB 

KRF (Indexed files only) 

MBC (disk Sequential files only) 

MBF (Relative and Indexed files only) 
ROP 

UBF (see RBF under “Output RAB Fields") 


8.2.1.2 Output RAB Fields - 
ISI 
RBF (= UBF value for Locate Mode on Sequential files) 


STS 
STV 


8.2.1.3 General Form - 
SCONNECT rab[,error[,success] ] 


where rab is the address of a Record Access Block you want connected 
to a FAB. 


error is the address of a completion routine to be called if the 
SCONNECT operation fails. 


success is the address of a completion routine to be called if the 
SCONNECT operation succeeds. 
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8.2.2 SDELETE 

The SDELETE macro deletes an existing record from a Relative or In- 
dexed file. If your program initiates a delete operation on a Sequen- 
tial file, RMS-11l returns error code ERSIOP. 

The SDELETE operation always applies to the Current Record. 
Therefore, your program must successfully execute a SFIND or S$GET 


macro before initiating a SDELETE macro; otherwise, RMS-11 returns 
error code ERSCUR. 


8.2.2.1 Input RAB Fields - 
BID 
BLN 


ISI 
ROP 


STS 
STV 


8.2.2.3 General Form - 
SDELETE rab[,error[,success}] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


error is the address of a completion routine to be called if the 
SDELETE operation fails. 


success is the address of a completion routine to be called if the 
SDELETE operation succeeds. 
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8.2.3 SDISCONNECT 
The SDISCONNECT macro terminates a Record Access Stream, ending the 


association between a FAB and a RAB. RMS-11 releases all buffer space 
for reuse. 


8.2.3.1 Input RAB Fields - 
BID 


BLN 
Ist 


8.2.3.2 Output RAB Fields - 
ISI (set to zero) 


STS 
STV 


8.2.3.3 General Form - 
SDISCONNECT rab[,error[,success] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


error is the address of a completion routine to be called if the 
SDISCONNECT operation fails. 


success is the address of a completion routine to be called if the 
SDISCONNECT operation succeeds. 


8.2.3.4 Comments - The S$DISCONNECT macro does not rewind magnetic 
tape files. If you want the file positioned to beginning-of-file for 
a subsequent connect operation, use the $REWIND macro before initiat- 
ing the disconnect operation. 
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8.2.4 SFIND 


The S$FIND macro locates a specified record in a file and returns its 
Record's File Address in the RAB RFA field. During the operation, 
RMS-11 sets the Current Record pointer and for Sequential Access Mode 
only, the Next Record pointer. 


8.2.4.1 Input RAB Fields - 


BID 

BLN 

ISI 

KBF (Random Access Mode only) 

KRF (Random Access Mode on Indexed files only) 
KSZ (Random Access Mode only) 

RAC 

RFA (if RAC contains RBSRFA) 

ROP 


8.2.4.2 Output RAB Fields - 
BKT (Sequential Access Mode on Relative files only) 
RFA (if RAC does not contain RBSRFA) 


STS 
STV 


8.2.4.3 General Form - 
SFIND rab[,error[,success] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


error is the address of a completion routine to be called if the 
SFIND operation fails. 


success is the address of a completion routine to be called if the 
SFIND operation succeeds. 
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8.2.4.4 Comments - 


RMS-11 allows Access by RFA during find operations on disk files 
only. 


Normally, you would not use Access by RFA for find operations on 
Relative and Indexed files, since the output of the operation is 
the RFA used as input. However, a find by RFA returns error code 
ERSDEL if the specified record once existed in the file, but was 
subsequently deleted: a random find operation returns error code 
ERSRNF whether the record never existed or was deleted. 


In Sequential Access Mode, a find operation on an Indexed file uses 
the index of reference set by the most recent successful get, se- 
quential find, or connect operation. If you want to use a differ- 
ent index for sequential processing, you should execute a rewind or 


a random get operation specifying the key of reference (RAB KRF 
field) you want. 


If the file allows duplicates in the key of reference, RMS-1l does 
not indicate if the record located is one of a series containing 
duplicates in that field. 
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8.2.5 S$FLUSH 

The SFLUSH macro writes all modified I/O buffers associated 
cord Access Stream to disk, if they haven't been written. 
operation, you can ensure that all record activity up to a 


time is reflected in the file. For Relative and Indexed 
bucket locked by the stream remains locked. 


8.2.5.1 Input RAB Fields - 
BID 


BLN 
Ist 


8.2.5.2 Output RAB Fields - 


STS 
STV 


8.2.5.3 General Form - 
SF LUSH rab[,error[,success] ] 


where rab is the address of a Record Access Block represent 
cord Access Stream. 


error is the address of a completion routine to be call 
SFLUSH operation fails. 


success is the address of a completion routine to be call 
SFLUSH operation succeeds. 
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8.2.6 SFREE 


The S$FREE macro unlocks a bucket that RMS-11 locked on behalf of a Re- 
cord Access Stream. If no bucket is locked, RMS-11l returns error code 
ERSRNL. 


See Chapter 2 of the RMS-11 User's Guide for more information on file 
sharing. 


8.2.6.1 Input RAB Fields - 


BID 
BLN 
ISI 


8.2.6.2 Output RAB Fields - 


STS 
STV 


8.2.6.3 General Form - 
SFREE rab[,error[,success] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


error is the address of a completion routine to be called if the 
SFREE operation fails. 


success is the address of a completion routine to be called if the 
SFREE operation succeeds. 


8.2.6.4 Comments - If you are uSing multiple Record Access Streams to 
access a file, you must not merely reissue a record operation that 
fails with error code ERSRLK. Since one of your program's streams can 
have the target bucket locked, you could place the program into an in- 
finite loop if you continue to iSsue the same operation. Therefore, 
you should execute a S$FREE macro for all other streams to the same 
file. Then you can safely reinitiate the original record operation 
until RMS-11 indicates successful completion. 
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8.2.7 S$GET 


The SGET macro retrieves a record from an RMS-11 file, moving the re- 
cord from the I/O buffer to your program's user buffer* and returning 
the record's RFA in the RAB RFA field. After a successful operation, 
the RAB RBF and RSZ fields describe the retrieved record with the ad- 
dress of its first byte and its length, respectively. 


8.2.7.1 Input RAB Fields - 


BID 

BLN 

ISI 

KBF (Random Access Mode only) 

KRF (Random Access Mode on Indexed files only) 
KSZ (Random Access Mode only) 

RAC 

RFA (if RAC contains RBSRFA) 

RHB (VFC records only) 

ROP 

UBF (regardless of Record Transfer Mode) 
USZ 


8.2.7.2 Output RAB Fields - 


BKT (Sequential Access Mode on Relative files only) 
RBF 


RFA (if RAC does not contain RBSRFA) 
RSZ 
STS 
STV 


8.2.7.3 General Form - 
SGET rab[,error[,success] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


*Unless you specify Locate Record Transfer Mode (RBSLOC in the RAB ROP 
field). 
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8. 


error is the address of a completion routine to be called if the 
SGET operation fails. 


success is the address of a completion routine to be called if the 
SGET operation succeeds. 


2.7.4 Comments - 


After a successful get operation from a unit record device, such as 
a terminal, the less significant byte of the RAB STV field contains 
a code representing the character that terminated the input record, 
as follows: 


Code Character 
(in octal) Represented 


15 Carriage Return 
33 Escape 

32 CTRL/Z 

0 other 


Except when the code is 0, the terminating character is never in 
the record described by the RAB RBF and RSZ fields. 


Example SGET ;RETRIEVE A RECORD 
CMPB #0, OSSTS (R5) 7;CHECK IF TERMINATOR STILL IN RE- 
CORD 


RMS-11 allows Access by RFA during get operations on disk files 
only. 


Normally, you would not use Access by RFA for get operations on Re- 
lative and Indexed files, since the output of the operation is the 
RFA used as input. However, a get by RFA returns error code ERSDEL 
if the specified record once existed in the file, but was subse- 
quently deleted: a random get operation returns error code ERSRNF 
whether the record never existed or was deleted. 


In Sequential Access Mode, a get operation not preceded by a  suc- 
cessful find uses the index of reference set by the most recent 
successful get, find, or connect operation. If you want to use a 
different index for sequential processing, you should execute a 
rewind or a random get or find operation specifying the key of 
reference (RAB KRF field) you want. 


If the file allows duplicates in the key of reference, RMS-11 does 
not indicate if the record retrieved is one of a series containing 
duplicates in that field. 
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8.2.8 SNXTVOL 


The SNXTVOL macro can be used only when the Record Access Stream is 
accessing a multivolume file on magnetic tape. You execute this macro 
when you want to continue processing the current file on the next vo- 
lume before the end of the current volume is reached. See also the 
magnetic tape handling appendix of the RMS-11 User's Guide. 


Next-volume processing depends on whether your program is reading or 
writing data on the tape: 


Input File Processing 


1. RMS-11 skips all records in I/O buffers for the current 
file section. 


2. $RMS-11 requests the next tape volume from the file pro- 
cessor: 


e If there is no next volume, RMS-1l returns error code 
ERSEOF. 


e If there is another volume, the file processor 
rewinds the current volume, requests the system oper- 
ator to mount the next volume, and reads the header 
label (HDR1) of the first file section on the next 
tape. If the tape is not the proper volume, the pro- 
cessor requests the operator to mount the correct 
tape and repeats this step. 


3. The operation terminates. 


Output File Processing 


1. RMS-11 writes I/O buffers to the current file section in 
an implicit flush operation. 


2. RMS-11 requests the next tape volume from the file  pro- 
cessor: 


a. The processor closes the current file section, writ- 
ing EOV1 and EOV2 labels and rewinding the volume. 


b. The processor requests the system operator to mount 
the next volume. 


c. The processor creates a file with the same name and 
the next higher section number and opens the file 
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for write operations. The file set identifier is 
identical with the volume identifier of the first 
volume in the volume set. 


3. The operation terminates. 


8.2.8.1 Input RAB Fields - 
BID 


BLN 
Ist 


8.2.8.2 Output RAB Fields - 


TS 
TV 


U3 


8.2.8.3 General Form - 
SNXTVOL rab[,error[,success] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


error is the address of a completion routine to be called if the 
SNXTVOL operation fails. 


success is the address of a completion routine to be called if the 
SNXTVOL operation succeeds. 
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8.2.9 SPUT 


The SPUT macro writes a new record into an RMS-11 file. The RAB’ RBF 
and RSZ fields describe the record to be written. You cannot use Ac- 
cess by RFA. Put operations in Random Access Mode do not change the 
Next Record pointer. 


8.2.9.1 Input RAB Fields - 


BID 

BLN 

ISt 

KBF (Random Access Mode on Relative files only) 
KSZ (Random Access Mode on Relative files only) 
RAC 

RBF 

RHB (VFC records only) 

ROP 

RSZ 

UBF (Locate Mode for Sequential files only) 

USZ (Locate Mode for Sequential files only) 


8.2.9.2 Output RAB Fields - 


BKT (Sequential Access Mode on Relative files only) 
RBF (Locate Mode for Sequential files) 
RFA 


STS 
STV 


8.2.9.3 General Form - 
SPUT rab[,error[,success] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream, 


error is the address of a completion routine to be called if the 
S$PUT operation fails. 


success is the address of a completion routine to be called if the 
SPUT operation succeeds. 
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8.2.9.4 Comments - 


e Since RMS-11 supports put operations in Sequential Access Mode only 
for Sequential files, you must set the value RBSSEQ in the RAB RAC 
field before initiating a $PUT operation on a Sequential file. 


e RMS-11 supports put operations only at the end of Sequential files. 
Your program can reach end-of-file by one of the following methods: 


-- Set RBSEOF in the RAB ROP field before initiating the connect 
operation. RMS~11 sets the Current Record pointer to 
end-of-file. 


-- Execute S$FIND (or $GET) macros until RMS-11l returns error code 
ERSEOF. 


e RMS-11 restricts put operations on Relative files as follows: 


-- No record can be written that is longer than the Maximum Record 
Size specified when the file was created. 


-- The cell specified by the contents of the RAB KBF field cannot 
contain a valid record--unless you set the value RBSUIF in the 
RAB ROP field. 


-- The relative record number in the RAB KBF field cannot be gre- 
ater than the Maximum Record Number specified when the file was 
created. 


e RMS-11 restricts put operations on Indexed files as follows: 


-- No record can be written that is longer than the Maximum Record 
Size specified when the file was created. 


~- No record can be written that is too short to contain the com- 
plete Primary Key field. The record does not have to contain 
all defined Alternate Key fields. 


e If a put operation on an Indexed file specifies a record that con- 
tains a key value already existing in the file, RMS-11 response de- 
pends on whether you allowed duplicate key values when you created 
the file: 


-- If duplicates are not allowed, RMS-11 returns error code ERSDUP. 
-- If duplicates are allowed, RMS-11l inserts the record after all 


records with the same key value and before a record with a 
higher key value. Then RMS-11 returns success code SUSDUP. 
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8.2.10 SREWIND 

The SREWIND macro sets the context of a Record Access Stream to the 
logical beginning of the associated file. Following the operation, 
there is no Current Record, and the Next Record is the first record in 


the file; for Indexed files, the value of the RAB KRF sets the index 
that defines the first record logically. 


8.2.10.1 Input RAB Fields - 
BID 
BLN 


ISI 
KRF (Indexed files only) 


8.2.10.2 Output RAB Fields - 


STS 
STV 


8.2.10.3 General Form - 
SREWIND rab[,error[,success] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


error is the address of a completion routine to be called if the 
SREWIND operation fails. 


success is the address of a completion routine to be called if the 
SREWIND operation succeeds. 


8.2.10.4 Comments - RSTS/E does not support the SREWIND macro. for 
magnetic tape files only. 
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8.2.11 S$TRUNCATE 

The STRUNCATE macro truncates a Sequential file. If you initiate a 
truncate operation on a Relative or Indexed file, RMS-11l returns error 
code ERSIOP. 

A truncate operation deletes the Current Record and all records fol- 
lowing that record and sets Next Record to point to the end-of-file. 
Therefore, your program must successfully execute a S$FIND or S$GET 


macro before initiating a $UPDATE macro; otherwise, RMS-1l returns 
error code ERSCUR. 


8.2.11.1 Input RAB Fields - 
BID 


BLN 
Ist 


8.2.11.2 Output RAB Fields - 


STS 
STV 


8.2.11.3 General Form - 
STRUNCATE rab[,error[,success]} ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


error is the address of a completion routine to be called if the 
STRUNCATE operation fails. 


success is the address of a completion routine to be called if the 
STRUNCATE operation succeeds. 


8.2.11.4 Comments - Your program can follow a truncate operation im- 
mediately with one or more sequential put operations. 
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8.2.12 SUPDATE 


The SUPDATE macro replaces an existing record with the record des- 
cribed by the RAB RBF and RSZ fields. 


The SUPDATE operation always applies to the Current Record. 
Therefore, your program must successfully execute a $FIND or SGET 
macro before initiating a SUPDATE macro; otherwise, RMS-ll returns 
error code ERSCUR. 


RMS-11 error codes indicating an illegal input value in a RAB field do 
not affect the record being updated. 


Example ERSRSZ 
However, other errors can mean that the target record is lost. 


Example ERSWER 


8.2.12.1 Input RAB Fields - 


BID 
BLN 
Isl 
RBF 
RHB (VFC records only) 
RSZ 


8.2.12.2 Output RAB Fields - 
RFA 


STS 
STV 


8.2.12.3 General Form - 
SUPDATE rab[,error[,success] ] 


where rab is the address of a Record Access Block representing a Re- 
cord Access Stream. 


error is the address of a completion routine to be called if the 
SUPDATE operation fails. 
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Success is the address of a completion routine to be called if the 
SUPDATE operation succeeds. 


8.2.12.4 Comments - 

e RMS-11 restricts update operations on Sequential files as follows: 
-- No updates on magnetic tape files or unit record devices. 
-- No updates on disk Sequential files with stream format records. 


-- No updates that change the length of the target record: your 
program must not change the RAB RSZ field between the get or 
find operation and the update operation. 


e For Relative files, the replacement record cannot be longer’ than 
the Maximum Record Size specified when the file was created. 


e For an update operation on an Indexed file that allows duplicate 
Primary Keys, the replacement record length must equal the target 
record length; that is, your program must not change the RAB RSZ 
field between the get or find operation and the update operation. 


e For an update operation on an Indexed file that does not allow du- 
plicate Primary Keys, the record length can change, but the re- 
placement record cannot be longer than the file's Maximum Record 
Size or too short to contain the complete Primary Key field. 
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8.2.13 SWAIT 


The S$WAIT macro suspends your program's operation until an outstanding 
asynchronous record operation completes. 


8.2.13.1 Input RAB Fields - 
BID 


BLN 
ISI 


8.2.13.2 Output RAB Fields - 


STS 

STV 

plus fields of asynchronous record operation your program is wait- 
ing for 


8.2.13.3 General Form - 
SWAIT rab[,error[,success] ] 
where rab is the address of an asynchronous Record Access Block repre- 
senting a Record Access Stream with an asynchronous record 


operation in progress. 


error is the address of a completion routine to be called if the 
SWAIT operation fails. 


success is the address of a completion routine to be called if the 
SWAIT operation succeeds. 


Record Operation Macros: S$WAIT 8-33 


CHAPTER 9 


PERFORMING BLOCK I/0 


Block I/O allows you to bypass the record processing capabilities of 
RMS-11. Through macros described in this chapter, you can read and 
write the virtual blocks of a file. 


CAUTION 


Many elements of the internal structure of RMS-11 files are 
not visible during record processing. With Block I/0, 
however, you can examine these elements. 


Exercise extreme caution when altering the virtual blocks of 
RMS-ll-structured Sequential, Relative, or Indexed files. 


To use Block I/O, your program must do the following: 


l. Allocate one BDB for each stream* connected for Block I/O. You 
specify BDBs with the PSBDB macro between the POOLSB and POOLSE 
Macros (see Chapter 2). 


2. Allocate an I/O buffer with at least 512 bytes (to support file 
operations). Use one of the techniques described in Chapters 1 
and 2. If your program reads or writes more than one block at a 
time, allocate a buffer large enough to support all operations. 


3. Set one or both of the following values in the FAB FAC field be- 
fore initiating any file operation macros: 


FBSREA if you want to read blocks from an RMS-11 file 
FBSWRI if you want to write blocks to an RMS-1l file 
4. Initiate one of the following file operaton macros: 
SCREATE 
You create a file that can be processed only with Block 


I/O operations. RMS-11 restricts such files as follows: 


e disk or magnetic tape medium 


*RMS-11 permits a single Block I/O stream for Sequential files and 
multiple streams for Relative and Indexed files. 


e Sequential organization (FBSSEQ in the FAB ORG field) 
e Undefined record format (FBSUDF in the FAB RFM field) 
SOPEN 
You access a file with any RMS-11 file organization; 
however, you can use only Block I/0 operations to access 
data in the file. 
Set up a Record Access Block (see Chapter 4) and initiate a 
SCONNECT macro for each Record Access Stream. No stream can be 
connected to the file for record processing. 


Use the macros described in this chapter to processing data in the 
file. 


Disconnect each stream. 


Close the file. 


Table 9-1 summarizes the RMS-11 Block I/O macros. 


Table 9-1: RMS-11 Block I/O Macros 







Macro Name Description 


SREAD Retrieve a specified number of bytes from a virtual block. 





SWRITE Write a specified number of bytes to a virtual block. 






SSPACE Move a magnetic tape a specified number of blocks. 
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9.1 SREAD 
The SREAD macro retrieves a specified number of bytes from a file be- 


ginning on ae specified virtual block boundary. You must supply a 
word-aligned buffer for the data. 


9.1.1 Input RAB Fields 


BKT (VBN where read starts) 

ISI 

UBF (address for input buffer) 

USZ (size of input buffer as a multiple of two bytes) 


9.1.2 Output RAB Fields 


RBF (location of data read from file) 
RSZ (number of bytes read) 

STS 

STV 


9.1.3 General Form 


SREAD rab[,error[,success] ] 


where rab is the address of a Record Access Block containing the spec- 
ification for the read operation. 


error is the address of a completion routine to be called if the 
SREAD operation fails. 


success is the address of a completion routine to be called if the 
SREAD operation succeeds, 


9.1.4 Comments 


e You can read multiple blocks by specifying an appropriate multiple 
of 512 bytes in the RAB USZ field. 
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e The value RMS-11 returns in the RAB RSZ field does not count’ the 
terminator character received from a unit record or terminal dev- 
ice. The RAB STV field reports on that character; see the SGET 
record operation in Chapter 8. 


e If the RAB STS field contains ERSEOF, the RAB RSZ still contains 
the number of bytes transferred. 
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9.2 SWRITE 


The SWRITE macro writes a specified number of bytes into a file begin- 
ning on a specified virtual block boundary. 


9.2.1 Input RAB Fields 


BKT (VBN where write starts) 

Ist 

RBF (address of first byte of one or more blocks to be written) 
RSZ (size of data to be written as a multiple of two bytes) 


9.2.2 Output RAB Fields 


STS 
STV (actual number of bytes transferred) 


9.2.3 General Form 


SWRITE rab[,error[,success] ] 


where rab is the address of a Record Access Block containing the spec- 
ification for the write operation. 


error is the address of a completion routine to be called if the 
SWRITE operation fails. 


success is the address of a completion routine to be called if the 
SWRITE operation succeeds. 


9.2.4 Comments 


@ You can write multiple blocks by specifying an appropriate multiple 
of 512 bytes in the RAB RSZ field. 


e If the RAB RSZ does not contain an even multiple of 512 bytes, the 


number of bytes specified are written, but the disk contents of the 
unwritten portion of the last block affected are undefined. 
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9.3 SSPACE 
The SSPACE macro causes a magnetic tape file to move forward or  back- 


ward. The file must have been opened for Block I/O and reside of mag- 
netic tape; otherwise, RMS-11 returns error code ERSIOP. 


9.3.1 Input RAB Fields 


BKT (number of blocks to be spaced; sign indicates direction) 
ISI 
ROP (can contain RBSASY; see Chapter 4) 


9.3.2 Output RAB Fields 


STS 
STV (number of blocks spaced) 


9.3.3 General Form 


SS PACE rab[,error[,success] ] 


where rab is the address of a Record Access Block containing the spec- 
ification for the spacing operation. 


error is the address of a completion routine to be called if the 
SSPACE operation fails. 


success is the address of a completion routine to be called if the 
SSPACE operation succeeds. 


9.3.4 Comments 


RMS-11 examines only the lower addressed byte of the one-word BRT 
field. RMS-11 interprets this byte as a signed 15-bit integer: 


e A positive integer represents the number of blocks the file is to 
be spaced forward 
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@ A negative number represents the number of blocks the file is to be 
backspaced. 
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APPENDIX A 


RMS-11 COMPLETION CODES 


All RMS-11 file and record operations return a completion code _ into 
the STS field of the associated control block (FAB or RAB). A symbol- 
ic name is defined for each code, with one of the following forms: 


Successful completion codes: 
SUScod 
Error completion codes: 


ERScod 


where cod represents the success qualifier or the reason the operation 
failed. 


For certain error conditions, RMS-11 uses the STV field to communicate 
additional information to your program. The tables in this appendix 
list all instances where an STS code indicates the presence of further 
information in the STV field. 


A limited number of severe error conditions cause RMS-11 to uSe a 


fatal error crash routine. Section A.3 describes these conditions and 
the crash routine. 


A.1 


SUCCESSFUL COMPLETION CODES 


Table A-1 describes successful completion codes returned by RMS-11 op- 
erations. 


Table A-l: 


Symbolic Numeric STV Field 


Value Value Value 


SUSSUC 


SUSDUP 


SUSIDX 


SUSRRV 
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Successful Completion Codes 


RMS-11 code 


RMS~11 Successful Completion Codes 


Description 


Operation successful without 
qualification. 


Conditional success: A record 
inserted into an Indexed file by 
a put or update operation con- 
tains at least one key value 
present in another record. 


A put or update operation on an 
Indexed file ended successfully, 
but RMS-11 could not optimize 
the index structure during the 
operation. Therefore, RMS-11 
will require eéxtra I/O opera- 
tions to retrieve the record. 
With this success code, RMS-11 
can include an RMS-11 error code 
in the STV field of the control 
block to indicate why the index 
structure was not updated. 


No longer a valid completion 
code. See ERSRVU in Table A-2. 


A.2 ERROR COMPLETION CODES 


Table A-2 shows: 


@e the RMS-11 error completion codes in alphabetical order by symbolic 
value 


e the numeric values of the codes in both octal and decimal radix 
e a brief explanation of the cause of the error 


When Table A-2 indicates that the STV field contains a file processor 
code (with the term fipcode), refer to the description of such codes 
in one of the following manuals: 


e Error code appendix of the IAS/RSX-11 I/O Operations Reference Man- 
ual 


e User recoverable error messages in an appendix of the RSTS/E  Pro- 
gramming Manual. Note that the value returned in STV is the nega- 
tive of the decimal value shown in the Programming Manual. That 
is, if STV contains "-20.," look up "20." 


When Table A-2 indicates that the Status Value field contains an FSS 
directive error code (with the term fsscode), you should refer to the 
error code appendix of the RSTS/E System Directives Manual for a des- 
cription of the codes. 


Table A-2: RMS-11l Error Completion Codes 







Symbolic 
Value 


Numeric STV Field Description 
Value Value 






ERSABO 177760/-16. ERSSTK/ERSMAP|Operation aborted: Stack save 
area exhausted or memory resi- 


dent control structures corrupt- 






ed. 

ERSACC 177740/-32. fipcode File processor error: File pro- 
cessor could not access’ the 
file. 





ERSACT 177720/-48. File activity|precludes operation. 
Example You attempted to close 
a file before an asyn- 
chronous record opera- 
tion finished. 


(Continued on next page) 


Error Completion Codes A-3 


Table A-2 


Symbolic 


Value 





ERSAID 


ERSALN 


ERSALQ 


ERSANI 


ERSAOP 


ERSAST 


ERSATR 


ERSATW 


ERSBKS 


ERSBKZ 


ERSBLN 


ERSBOF 


A-4 


(continued) 


Numeric 
Value 








177700/-64. 


177660/-37. 


177640/-96. 


177620/-112. 


177600/-128. 


177560/-144. 


177540/-160. 


177530/-168 


177520/-176. 


177500/-192. 


177460/-208. 


177440/-224., 


177430/-232. 


STV Field 
Value 


XAB address 
XAB address 


XAB address 


XAB address 


fipcode 


fipcode 


XAB address 


Error Completion Codes 


Description 


The area indicated by the XAB 
does not exist in the file. 
Illegal alignment value for 
Placement Control. 

Illegal allocation quantity: 
The quantity exceeds 65K blocks 
during file creation on a 


non-Large Files RSTS/E system 
or equals zero during an expli- 
cit file extension operation. 


Records in a file on 
ANSI-labeled magnetic tape are 
variable-length, but not in 


ANSI-D format. 


Invalid type of allocation. 





Invalid operation at AST level: 
You attempted to issue a syn- 
chronous operation from an asyn-. 
chronous record operation com- 
pletion routine. 


File processor error: Read fai- 
lure on file attributes. 
Invalid File ID. See ERSFID. 


File processor error: Write fa- 
ilure on file attributes. 


File bucket size exceeds maximum 
for operating system. 


Area bucket size exceeds maximum 
for operating system. 


Control block (FAB, RAB, or XAB) 
length is invalid. 


Beginning of file detected dur- 
ing magnetic tape spacing opera- 
tion. 


er kimi NRE RN 
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Table A-2 





















Symbolic 
Value 


ERSBPA 





ERSBPS 





ERSBUG 








ERSCHG 


ERSCLS 





ERSCOD 









ERSCRE 


(continued) 


Numeric 


Value 


177420/-240. 


177400/-256. 


177360/-272. 


177340/-288. 


177320/-304. 


177300/-320. 


177260/-336 


177240/-352. 


177220/-368. 


STV Field 
Value 


fipcode 


XAB address 


fipcode 


Description 


Invalid 1/0 buffer: Private 
buffer pool not on word bounda- 
ry. 


Invalid I/0 buffer: Private 
buffer pool size not a multiple 
of two bytes. 


RMS-11 aborts your task because 
it detected an internal error. 
Contact a DIGITAL Software Spe- 
cialist. 


You attempted to connect more 
than one record access stream to 
a Sequential file. 


During an update operation, you 
attempted to change a key field 
that does not allow changes. 


Indexed file bucket corrupted. 
Do as many of the _ following 
steps as necessary: 

1. Move the disk pack containing 

the file to another device 
and try the process again. 
If it works, the error was 
caused by a hardware read fa- 
ilure. 
Recreate the file using’ the 
RMSIFL or RMSCNV utility. If 
this works, the corrupted 
bucket was in an index bucket 
not used during sequential 
access by Primary Key. 

3. Restore the file from your 
last backup copy. 


File processor error: During 
RMS-11 file close operation. 


XAB type is invalid for the or- 
ganization or operation. 


File processor error: File pro- 
cessor could not create file. 
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Error Completion Codes A-5 


Table A-2 (continued) 


Symbolic STV Field Description 
Value Value 











































ERSCUR 177200/-384. No Current Record: Delete, 
truncate, or update operation 
was not immediately preceded by 
a successful get or find. 


ERSDAC 177160/-370. fipcode File processor error: File pro- 
cessor deaccess failure during 
RMS-11 file close operation. 


ERSDAN 177140/-416. | XAB address Invalid area number specified in 
Key XAB DAN field. 


ERSDEL 177120/-432. Record accessed by RFA access 
mode has been deleted. 


ERSDEV 177100/-448. e Syntax error in device name 

e No such device 

e Inappropriate device for op- 
eration 


Example You attempted to 
create an Indexed 
file on magnetic 
tape. 


ERSDFW 177070/-456. fipcode File processor error: File pro- 
cessor could not write bucket; 
RMS-11 deferred the I/0 opera- 
tion until it needed the I/0 
buffer for another bucket be- 
cause the user program specified 
Deferred Write. 


ERSDIR 177060/-464. Syntax error in filespec  direc- 
tory name. 


ERSDME 177040/-480. Dynamic memory exhausted: An 
RMS-11 buffer pool has insuffi- 
cient free space. 
ERSDNF 177020/-496. Directory not found. 
ERSDNR 177000/-512. Device not ready. 


ERSDPE 176770/-520. fipcode Device positioning error. 





ERSDTP 176760/-528. | XAB address Invalid key data type. 
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A-6 Error Completion Codes 


Table A-2 (continued) 


Symbolic Numeric STV Field Description 
Value Value Value 


ERSDUP 













176740/-544. Invalid record operation: You 
attempted to insert a_ record 
that would cause duplicate va- 
lues in a key field where dupli- 


cates are not allowed. 





















ERSENT 176720/-560. File processor error: File pro- 
cessor could not enter filespec 


in directory. 
















176700/-576. You attempted an operation when 
the RMS-11 routines were not in 
the task: In MACRO-1l, the op- 
eration or file organization was 
not specified in ORGS macro; in 
BASIC-PLUS-2, you didn't specify 
correct switches with BUILD com- 
mand. 







ERSEOF 176660/-592. e For record processing: End 
of file. 


e For Block I/O: Invalid VBN. 










ERSESS 176640/-608. Expanded file-name string area 


in NAM Block is too short. 











ERSE XP 176630/-616. File expiration date not re- 


ached. 














ERSEXT 176620/-624, 





fipcode File processor error: During 


RMS-11 file extension operation. 

















ERSFAB 176600/-640. FAB BID field does not contain 


FBSBID. 

















ERSFAC 176560/-656. Invalid record operation: 
Operation does not match access 
declaration made when file was 


created or opened. 















ERSFEX 176540/-672. 





You tried to create a file that 


exists. 








ERSFID 177530/-168. Invalid file ID. 
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Error Completion Codes A-7 


Table A-2 


Symbolic 
Value 


176520/-688, 


(continued) 


Numeric 
Value 
















ERSFLG 


ERSFLK 176500/-704. 


ERSFND 176460/-720. 


ERSFNF 176440/-736. 


ERSFNM 176420/-752. 


ERSFOP 176400/-768. 


ERSFSS 176370/-776. 


ERSFUL 176360/-784. 


ERSIAN 176340/-370. 


ERSIDX 176320/-816. 


ERSIFI 176300/-832. 


STV Field 
Value 


XAB address 


fipcode 


fsscode 


XAB address 


Description 


Invalid combination of key char- 
acteristics. 


Example No duplicate key va- 
lues, but key values 
can change during up- 
date operations. 

File locked by another’ user: 

You cannot access the file be- 

cause your sharing specifica- 

tions cannot be met. 

File processor error: File pro- 


cessor could not find filespec 
in specified directory. 


File not found during file 
operation. 


open 


Syntax error in file-name. 


Invalid file access option spec- 
ified in FAB FOP field. 


RSTS/E monitor error: the 
File-name String routine is un- 
able to parse the file-name 
string supplied by RMS-11. 


Device full: RMS-11 cannot cre- 
ate or extend file. 


Invalid area number specified in 
Key XAB IAN field. 


Specified index was not created. 
This code can only occur in the 
STV field when STS contains 
ERSRNF. 

FAB IFI field invalid 
value. 


contains 








A-8 





Error Completion Codes 
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Table A-2 





Symbolic 
Value 












ERSIMX 





ERSINI 


ERSIOP 


ERSIRC 


ERSKBF 


ERSKEY 


(continued) 


Numeric 
Value 


176260/-848. 


176240/-864. 









176220/-880. 





176200/-896. 


176160/-912. 





176140/-928. 





176120/-944. 


STV Field 
Value 


XAB address 


Description 


More than 254 keys and/or areas 
defined or multiple Summary, 
Protection, or Date/Time XABs 
present during operation. 


SINIT or SINITIF macro call 
never issued. 


Illegal operation. 


Example You attempted to trun- 
cate a nonSequential 
file. 


Example You attempted to de- 
lete or extend a mag- 
netic tape file. 


Example You issued a Block I/O 
operation to a stream 
not connected for 
block operations. 


Example You issued a_e record 
operation to a stream 
connected for Block 
I/O operations. 


Illegal record encountered _ in 
Sequential file: Record-length 
field is invalid. 


RAB ISI field is invalid. You 
may have altered it or failed to 
connect the stream. 


No key specified during random 
record operation: RAB KBF field 
equals 0. 


Negative Relative Record Number 
during random operation or bad 
format in packed decimal key 
value. 


(Continued on next page) 


Error Completion Codes A-9 


Table A-2 (continued) 


Symbolic Numeric STV Field Description 
Value Value Value 


ERSKRF 176100/-960. Invalid key of reference: 
e During random get or find op- 
eration. 


e During connect or rewind op- 
eration: Error code is re- 
turned for the first sequen- 
tial get or find operation 
following the connect or 
rewind. 


ERSKSZ 176060/-976. Invalid key size. 


ERSLAN 176040/-992. | XAB address Invalid area number specified in 
Key XAB LAN field. 


ERSLBL 176020/-1008. Invalid medium: Magnetic tape 
is not labeled in accordance 
with ANSI standards. 


ERSLBY 176000/-1024. Logical channel busy: You at- 
tempted to create or open a file 
using a logical channel in use; 
that is, you already opened a 
file on that channel. 


ERSLCH 175760/-1040. Invalid logical channel or unit 
number. 


ERSLEX 175750/-1048.] XAB address You attempted to extend an area 
containing an unused extent. 


ERSLOC 175740/-1056.] XAB address Invalid location during Place- 
Ment Control. 


ERSMAP 175720/-1072. Memory-resident data structures, 
such as I/O buffers, corrupted. 
This code can occur in the STV 
field when Status Code contains 
ERSABO. 


ERSMKD 175700/-1088. fipcode File processor error: File pro- 
cessor could not mark file for 
deletion. 
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A-10 Error Completion Codes 


Table A-2 (continued) 


Symbolic Numeric STV Field Description 
Value Value Value 


ERSMRN 175660/-1104. Maximum Record Number’ field 
contains a negative value 
during creation of Relative 
file. 

Relative Record Number for 
random operation to Relative 
file exceeds Maximum Record 
Number specified when file 
was created. 


ERSMRS 175640/-1120. 


Maximum Record Size is zero dur- 

ing file creation and one of the 

following is true: 

e Record format is fixed 

e File organization is Rela- 
tive. 


ERSNAM 175620/-1136. 


Odd address in FAB NAM field on 
file open, creation, or erase 
operation. 

ERSNEF 175600/-1152. You attempted a put operation to 
a Sequential file when stream is 
not positioned to end-of-file. 
175560/-1168. Dynamic memory exhausted: Not 
enough buffer area to open an 
Indexed file. 

ERSNPK 175540/-1184, You attempted to create an In- 
dexed file without defining a 
Primary Key. 


ERSOPN 175520/-1200. fipcode File processor error: During 
RMS-11 file open operation. 


ERSORD 175500/-1216.| XAB address XABsS not ordered properly. 





ERSORG 175460/-1232. Invalid file organization. 
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Error Completion Codes A-ll 


Table A-2 (continued) 


Symbolic Numeric STV Field 
Value Value Value 


Description 





ERSPLG 175440/-1248. A Prologue block may be corrupt- 
ed. Do as many of the following 
steps as necessary: 

1. Move the disk pack containing 
the file to another device 
and try the process again. 
Tf it works, the error was 
caused by a hardware read fa- 
ilure. 

2. Recreate the file using’ the 
RMSIFL or RMSCNV utility. 

3. Restore the file from your 
last backup copy. 

ERSPOS 175420/-1264.| XAB address You specified a key position 
beyond the end of the record. 
ERSPRM 175400/-1280.] XAB address File directory entry contains 
date and time information not 
semantically correct. The file 
may be corrupted. Recreate 
field using RMSIFL or RMSCNV 
utility. 

ERSPRV 175360/-1296. Privilege violation: access to 

the file denied by the operating 

system. 

ERSRAB 175340/-1312. RAB BID field does not contain 

RBSBID. 

ERSRAC 175320/-1328. Invalid or illogical record ac- 

cess option specified in RAB RAC 

field. 

175300/-1344. You specified both Carriage Re- 

turn control and FORTRAN forms 

control. 

ERSRBF 175260/-1360. RAB RBF field contains an odd 

address (Block I/O access only). 

ERSRER 175240/-1376. fipcode File processor error: 

e In record processing: Read 
failure on file block. 

e In Block I/O, VBN = QO, an 
illegal value. 
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A-12 Error Completion Codes 


Table A-2 (continued) 







Numeric 
Value 


Symbolic 
Value 






ERSREX 175220/-1392. 






ERSRFA 175200/-1408. 






ERSRFM 175160/-1424. 







ERSRLK 175140/-1440. 







ERSRMV 175120/-1456. 






ERSRNF 175100/-1472. 







ERSRNL 175060/-1488. 







ERSROP 175040/-1504. 







ERSRPL 175020/-1520. 






ERSRRV 175000/-1536. 







ERSRSA 174760/-1552. 





ERSRSZ 174740/-1568. 


STV Field 
Value 


fipcode 


ERSIDX 


fipcode 


Description 


Record exists: During a put op- 
eration in random mode to a Re- 
lative file, you tried to insert 
a record into a cell containing 
a record. 


Invalid RFA during RFA access. 
Invalid record format. 


Target bucket locked by another 
task or another stream in the 
same program. 


File processor error: File pro- 
cessor could not remove filespec 
from directory. 


Record specified during random 
get or find operation does not 
exist in Relative or Indexed 
file. For Indexed files only, 


STV may contain ERSIDX. 


You initiated a free operation, 
but no bucket was locked. 


Invalid record processing option 
or illogical combination of va- 
lues specified in RAB ROP field. 
File processor error: Read fai- 
lure on file Prologue. 

Invalid RRV record encountered 
in Indexed file. File may be 
corrupted. Recreate field using 
RMSIFL or RMSCNV utility. 


Record stream active: In asyn- 
chronous environment, you at- 
tempted a record operation on a 
stream that is performing an op- 
eration. 


e Record size is zero 
Block I/O. 


during 
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Error Completion Codes A-13 


Table A-2 (continued) 


Symbolic Numeric STV Field 
Value Value Value 





Description 


e Record size exceeds one of 
the following: 

-- MRS for variable-length or 
VFC records. 

-- magnetic tape block size. 

-- data bucket size of In- 
dexed file. 

-~- 510(10) bytes and 
spanning not allowed. 

-- end of I/O buffer during 
Locate Mode put operation 
on Sequential file. 

e Record is too short to con- 
tain Primary Key of Indexed 
file. 

e Record size is not 
size of Current Record for 
update operation on a disk 
Sequential file or on an In- 
dexed file where Primary Key 
duplicate are allowed. 

e Record size does not equal 
MRS for fixed-length records. 


block 


equal _ to 


Record too big for user buffer: 
RMS-11 could not move entire re- 
cord retrieved by get operation 
to user buffer. This error does 
not destroy the context of the 
stream. Rather, the stream's 
context is updated as if the op- 
eration were completely success—_ 
ful and as much of the record as 
possible is moved to the user 
buffer. 


During a put or update opera- 
tion, RMS-11 moved the specified 
record to the file successfully, 
but could not update one or more 
Record Reference Vector (RRV). 
The file is corrupted, but you 
can retrieve every record via 
the Primary index. Therefore, 
you should create a new’ Indexed 
file and populate it from the 


bad file using either the RMSIFL 
or the RMSCNV utility. 








ERSRTB 174720/-1584.|Bytes moved 
ERSRVU 174710/-1592. 
A-14 Error Completion Codes 


(Continued on next page) 


Table A-2 (continued) 







Symbolic 
Value 


Numeric STV Field Description 
Value Value 





ERSSEQ 174700/-1600. Invalid record operation: 

During a sequential put opera- 
tion to an Indexed file, Primary 
Key of record to be written is 
not equal to or greater than key 


of previous record. 








ERSSHR 174660/-1616. You specified allow write de- 


claration for Sequential file. 










ERSS1IZ 





174640/-1632.] XAB address Invalid key size. 





Example Key is bigger than 
Maximum Record Size. 





ERSSTK 174620/-1648. During asynchronous record oper- 
ation, RMS-11 found the stack 
too big to saved. This code can 
only occur in the STV field when 


Status Code contains ERSABO. 









ERSSYS 





174600/-1664.| Directive or} The interface between RMS-11 and 
QIO status the operating system has 
error code changed. Report this error on 


an SPR to DIGITAL. 





ERSTRE 174560/-1680. Index in Indexed file is cor- 
rupted. Recreate file using 


RMSIFL or RMSCNV utility. 










ERSTYP 1174540/-1696. | 


Syntax error in extension, such 
aS more than three characters 
specified. 









ERSUBF 174520/-1712. 


User buffer improperly 
specified: address is either 
Zero Or buffer is not 
word-aligned (for Block I/0 ac- 
cess only). 









ERSUSZ 






174500/-1728. User buffer length equals zero. 





ERSVER 174460/-1744 Syntax error in file version 


number. 










ERSVOL 





174440/-1760. 





XAB address Nonzero relative volume number. 
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Error Completion Codes A-15 


Table A-2 (continued) 












STV Field 
Value 


Numeric 
Value 













Symbolic 
Value 


Description 


174430/-1768. Explicit or default file specif- 
ication field contains wild card 


character. 






ERSWER 174420/-1776. File processor error: Write fa- 


ilure on file block. 






ERSWLK 174410/-1784. File processor error: Device is 


write locked. 








ERSWPL 174400/-1792. File processor error: Error 


while writing Prologue. 


fipcode 





FAB XAB field or XAB NXT field 
contains an odd address. 





ERSXAB 174360/-1808.| XAB address 


ERSXTR 174340/-1824. 





Explicit or default file specif- 
ication contains extraneous 
field. 


A-16 Error Completion Codes 


A.3 FATAL ERROR CRASH ROUTINE 


RMS-11 issues a BPT instruction whenever it encounters an inconsistent 
internal conditions. This action is taken only when RMS-11 cannot 
continue processing because it might damage your files or task image. 


Example When RMS-11 encounters an invalid FAB or RAB, it cannot per- 
form a normal error routine because it has no recognizable 
control block to set a status code in. 


The BPT instruction generated is in the RORMSA module of RMS-1l. The 
general registers contain the following values at the time this in- 
struction is executed: 


RO = RMS-11 error code 

Rl = Entry Stack Pointer value 

R2 = Entry return Program Counter 
R3 = Address of system impure area 


General registers Rl and R2 are always valid if the crash routine is 
caused by a fatal user call error (described in Section A.3.1). When 
the crash routine is used because of inconsistent internal conditions 
(described in Section A.3.2), the contents of Rl and R2 can be mean- 
ingless if RMS-11 was executing an asynchronous record operation. 


A.3.1 Fatal User Call Errors 


If general register RO contains 176600(8) (ERSFAB) or 175340(8) 
(ERSRAB), your program initiated an RMS-11 operation using an invalid 
control block: FAB for file operations and RAB for record operations. 
This condition can occur for any one of the following reasons: 


e The address of the control block is 0. 
e The address of the control block is odd. 


e The control block's BID field does not contain the proper block 
identifier code: FBSBID for FABs and RBSBID for RABs. 


Example On RSX-11M, a fatal user call error resulted in: 


TASK "TTnn " TERMINATED 
T BIT TRAP OR BPT EXECUTION 

PC=021144 

PS=170004 

RO0=175340 

R1=001162 

R2=003646 

R3=045276 

R4=000000 

R5=001164 

SP=001126 


RMS-11 Fatal Error Crash Routine A-17 


A.3.2 RMS-11 Inconsistent Internal Conditions Errors 

If general register RO contains 177360(8) (ERSBUG) or 175720(8) 
(ERSMAP), RMS-11 encountered a fatal internal problem. Such condi- 
tions can be caused by your program (destroying some internal RMS-1ll 
data base, for example), but RMS-11 can also be responsible. 

If one of your tasks crashes with one of these error codes, send a 
Software Performance Report (SPR) to DIGITAL with the following infor- 
mation: 

e The contents of the general registers 

e The first ten words, at a minimum, or all words on the system stack 
e The operation your task was performing (open, get, put, and so on) 
e The organization of the file being processed 


e A load map of the task (produced by the Task Builder utility) 


® A post-mortem dump 


A-18 RMS-11 Fatal Error Crash Routine 


APPENDIX B 


SAMPLE CODE SEGMENTS 


The programs and code segments included in this appendix work; that 
is, they run, performing the indicate RMS-11l operations, without 
error. They are samples of programs that do run, but you should not 


construe them to be examples of approved programming techniques. 


B.1 COPYING SEQUENTIAL FILES 


The sample code segments in this section demonstrate the copying of 
records from an existing Sequential file to a new Sequential file. 


; DEMO. RMS 


PROGRAM TO COPY RECORDS FROM A SEQUENTIAL FILE NAMED 
; FILE1.DAT TO A NEW SEQUENTIAL FILE NAMED FILE2.DAT 
; STEP 1: ACCESS THE NECESSARY RMS MACROS 
-MCALL S$INIT,ORGS,FABSB, RABSB,POOLSB, S$CREATE,SOPEN,$CLOSE 
-MCALL $CONNECT,$GET,$PUT,SFETCH,SSTORE, $COMPARE 


a 

;STEP 2: DEFINE CONTROL BLOCKS AND FILE NAME STRINGS 
;THE FAB FOR THE INPUT FILE, WHICH ALREADY EXISTS, WILL BE 
;FILLED WITH MOST OF THE ESSENTIAL INFORMATION CONCERNING 
;FILEL.DAT WHEN THE FILE IS OPENED. THE PROGRAM NEED ONLY 
7;SPECIFY ENOUGH INFORMATION TO OPEN THE FILE. 


; 
FABI1: FABSB ;FAB FOR FILE1.DAT 


FSFNA NAME1 ; ADDRESS OF NAME STRING 
FSFNS 9 ;STRING IS 9 CHARACTERS LONG 
FSLCH 1 ;ACCESS ON CHANNEL 1 
FABSE ;END OF FABL 

NAME]: .ASCII /FILE1.DAT/ ;NAME STRING FOR FABL 


;HERE, AND WITH FILE2, WE ASSUME THAT THE FILE EXISTS 
;ON THE SYSTEM DISK UNDER THE ACCOUNT ON WHICH WE ARE 
;LOGGED IN. 

» EVEN ; (CONTROL BLOCKS MUST BE WORD ALIGNED) 


Ud 

;THE FAB FOR THE OUTPUT FILE, WHICH DOES NOT YET EXIST, MUST 

;BE FILLED WITH THE INFORMATION NECESSARY TO CREATE IT (AS IN 
;THE PREVIOUS CASE, SOME FIELDS SIMPLY CONTAIN DEFAULT VALUES 
;AND ARE NOT EXPRESSED EXPLICITLY). SOME OF THIS INFORMATION 


;WILL DEPEND ON THE CHARACTERISTICS OF FILE1.DAT, AND MUST BE 
;FILLED IN AT RUN-TIME AFTER FILE1.DAT HAS BEEN OPENED. 


FAB2: FABSB ;FAB FOR FILE2.DAT 
FSFNA NAME2 ;ADDRESS OF NAME STRING 
FSFNS 9 ;STRING IS 9 CHARACTERS LONG 
FSLCH 2 ;ACCESS ON CHANNEL 2 
FSFAC FBSPUT ;WRITE ACCESS REQUIRED 
FABSE ;END OF FAB2 
NAME2: .ASCII /FILE2.DAT/ NAME STRING FOR FAB2 
- EVEN 
RABI: RABSB ;RAB FOR FILE1. DAT 
RSFAB FAB1 ;ADDRESS OF OWNER (FAB) 
RSRAC RBSSEQ ;SPECIFY SEQUENTIAL ACCESS 
RSUBF RECBUF ;ADDRESS OF RECORD BUFFER FOR SGETS 
RSUSZ 500 ;SIZE OF THIS BUFFER (500. BYTES) 
RSRHB HEDBUF ;ADDRESS OF RECORD HEADER BUFFER 
; (NECESSARY FOR VFC RECORDS ONLY) 
RABSE ;END OF RABI 
RAB2: RABSB RAB FOR FILE2. DAT 
RSFAB FAB2 ;ADDRESS OF OWNER 
RSRAC RBSSEQ ;SPECIFY SEQUENTIAL ACCESS 
RSRBEF RECBUF ;ADDRESS OF RECORD BUFFER FOR $PUTS 
RSRSZ 500 ;SIZE OF THIS BUFFER (500. BYTES) 
RSRHB HEDBUF ;ADDRESS OF RECORD HEADER BUFFER 
; (NECESSARY FOR VFC RECORDS ONLY) 
RABSE 7;END OF RAB2 
‘ 
7;STEP 3: ALLOCATE THE BUFFERS SPECIFIED ABOVE 
RECBUF: .BLKW 250. 
HEDBUF: .BLKW 128. 
ld 
7STEP 4: GENERATE RMS INTERNAL SPACE POOL 
POOLSB ;BEGIN POOL SPECIFICATION 
PSFAB 2 ;A FAB FOR EACH FILE 
PSRAB 2 7A RAB FOR EACH FAB 
PSBDB 2 ;AN I/O BUFFER FOR EACH RAB 
PSBUF 1024 ;MINIMUM BUFFER SIZE IS 512. BYTES 
POOLSE 7;END OF POOL SPECIFICATION 
, 
;STEP 5: DEFINE THE RMS FUNCTIONALITY REQUIRED 
ORGS SEQ,<CRE,GET, PUT> ;SEQUENTIAL FILES ONLY, S$FIND, 
;SUPDATE, SDELETE NOT REQUIRED 
’ 
;STEP 6: PROVIDE A GENERAL ERROR ROUTINE TO HANDLE UNEXPECTED 
; ERRORS WHICH MIGHT OCCUR (WHAT IF FILE1.DAT DID NOT 
: EXIST, OR CONTAINED A RECORD LARGER THAN 500 BYTES?). 
. THIS IS AN ALTERNATIVE TO THE 'COMPLETION ROUTINE' 
7 FUNCTION PROVIDED BY RMS. 
ERROR: ; (CODE WHICH WILL HANDLE THE ERROR, PROMPT AT THE TERMINAL FOR 
;FURTHER INSTRUCTIONS, ETC.) 
7 
;STEP 7: WRITE THE PROGRAM 
’ 
START: SINIT ;INITIALIZE RMS. 
SOPEN #FAB1 ;OPEN FILE1.DAT, 
MOV #FAB1,RO :;SET UP FOR SCOMPARE: 
B-2 Sample RMS-11 Programs 


Lo: 


3$ 


4S: 


5$ 


6S: 
DON 


18; 


SCOMPARE #0,STS,RO ;NEG STS VALUE MEANS OPEN FAILURE 


BGT 1s ;BRANCH IF SUCCESSFUL 

JSR PC, ERROR ;OTHERWISE EXECUTE ERROR ROUTINE. 

MOV #FAB2,R1 ;COMPLETE INITIALIZATION OF FAB2: 
SFETCH R2,RAT,RO ;GET RAT FIELD FROM FABI1 

SSTORE R2,RAT,RI1 ;AND MOVE IT INTO FAB2; 

SFETCH R2,RFM,RO ;DO THE SAME WITH THE RFM FIELD; 
SSTORE R2,RFM,R1 

SFETCH R2,FSZ,RO ;FSZ IS PERTINENT ONLY IF FILE1.DAT 
SSTORE R2,FSZ,R1 ;MAY CONTAIN VFC RECORDS. 

SFETCH R2,MRN,RO ;YOU MAY OR MAY NOT WISH TO TRANSFER 
SSTORE R2,MRN,R1 ;MRN, MRS, AND FOP. IF MRN IS COPIED, 
SFETCH R2,MRS,RO ;REMEMBER THAT IT IS A 2-WORD FIELD, 
SSTORE R2,MRS,R1 ;AND WILL DESTROY THE CONTENTS OF R3. 


tf 

; INITIALIZATION OF FAB2 SHOULD NOW BE COMPLETE EXCEPT FOR ANY 
;SPECIAL CASES (FOR EXAMPLE, IF FILE2.DAT IS ON MAGNETIC TAPE, 
;YOU MAY WISH TO SET THE BLS FIELD). 

SFETCH R2,ALQ,RO 

SSTORE R2,ALQ,R1 


SCREATE Rl sNOW CREATE FILE2.DAT (R1=FAB2): 
SCOMPARE #0,STS,R1 ;CHECK FOR FAILURE 

BGT 2s ;BRANCH IF SUCCESSFUL 

JSR PC, ERROR ;OTHERWISE EXECUTE ERROR ROUTINE. 
MOV #RAB1, RO ;CONNECT THE RABS. 

MOV #RAB2,R1 

SCONNECT RO 

SCOMPARE #0,STS,RO 

BGT 38 ;BRANCH IF SUCCESSFUL 

JSR PC, ERROR 


SCONNECT R1 
SCOMPARE #0,STS,R1 


BGT 4S 

JSR PC, ERROR 

SGET RO ;GET A RECORD FROM FILE1.DAT. 
SCOMPARE #ERSEOF,STS,RO ;WERE WE AT END-OF-FILE? 

BEQ DONE ;IF SO, CLEAN UP AND EXIT. 
SCOMPARE #0,STS,RO ;SOME OTHER ERROR? 

BGT 5$ ;BRANCH IF SUCCESSFUL 

JSR PC, ERROR ;IF SO, HANDLE IT. 

SFETCH R2,RSZ,RO :COPY RECORD LENGTH FROM 
SSTORE R2,RSZ,R1 ;RAB1 TO RAB2. 

SPUT Rl ;OUTPUT THE RECORD TO FILE2.DAT. 
SCOMPARE #0,STS,R1 

BGT 6S ;BRANCH IF SUCCESSFUL 

JSR PC, ERROR 

BR 4S ; LOOP UNTIL DONE. 

MOV #FAB1,RO ;BACK TO THE FABS FOR SCLOSE. 
MOV #FAB2,R1 

SCLOSE RO 

SCOMPARE #0,STS,RO 

BGT 18 ;BRANCH IF SUCCESSFUL 

JSR PC, ERROR 

SCLOSE Rl 

SCOMPARE #0,STS,R1 

BGT 2$ 

JSR PC, ERROR 
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*RMS IS NOW DONE: FILE2.DAT NOW CONTAINS ALL THE DATA RECORDS 
;OF FILE1.DAT, PLUS OTHER INFORMATION (MRS, MRN, ETC.) 


7YOU CHOSE TO DUPLICATE. INSERT YOUR OWN EXIT CODE AND EXIT. 
- END START 


B-4 Sample RMS-11 Programs 


B.2 COUNTING WORDS IN A SEQUENTIAL FILE 


This sample program reads through a sequential file named RNO.DOC, 
noting pages and counting words. The program uses RMS~-1ll for terminal 
L/O. 


-TITLE WORDS.MAC 

-SBTTL READ A DOCUMENTATION FILE AND COUNT THE WORDS 
-ENABL REG ; SO CAN USE RO, Rl, ETC. 
-NLIST ME 

-NLIST BIN 


PROGRAM TO READ A DOC FILE PRODUCED BY RUNOFF OR RNO AND 
COUNT THE WORDS, 
STORING ENTRIES IN AN RMS ISAM FILE 


we Ne Me Me TO Me 


-MCALL EXITSS 

-MCALL ORGS, POOLSB,SINIT 

-MCALL SGNCAL,FABSB, RABS$B, XABSB 
-MCALL S$SFBCAL,SRBCAL 

SGNCAL 

SFBCAL 

SRBCAL 


; 

; THE FAB FOR THE INPUT DOC FILE, NAMED RNO.DOC, MUST 

; COMPLETELY DESCRIBE THE FILE AT ASSY TIME TO SAVE RUN TIME. 
; 


-SBTTL RMS-11 DATA BLOCKS 


. PAGE 
. EVEN 
DOCFAB: FABSB BEGIN MINIMUM INITIALIZATION 
FSBPA 0 NO PRIVATE BUFFER POOL 
FSBPS 0 DITTO 
FSDNA 0 USE SYSTEM DEFAULTS 
FSDNS 0 DITTO 


FSFAC FBSGET 
FSFNA DOCNAM 
FSFENS DOCNML 


ONLY GET RECORD OPERATIONS 
FILE NAME ADDRESS 
FILE NAME LENGTH 


FSFOP 0 NOT CONTIGUOUS 
FSLCH 1 LOGICAL CHANNEL FOR FILE 1 
FSNAM 0 NO NAM BLOCK 


FSORG FBSSEQ 
FSRFM FBSSTM 


FILE ORGANIZATION 
DOC FILES ARE STREAM 


FSRTV 0 VOLUME CLUSTERSIZE 

FSSHR 0 NOBODY ELSE 

FSXAB 0 NO XABsS 

FABSE END INITIALIZATION BLOCK 


me me TO Ne MO we Ne SO Ne MO me Ne we MO MO SO Me Ne 


DOCNAM: .ASCII /RNO.DOC/ 
DOCNML = .-DOCNAM 
i 


; NEED CRT TO OUTPUT MESSAGES TO TERMINAL RUNNING JOB 


ASSUME SYSTEM DEFAULTS 


; 

. EVEN 

CRTFAB: FABSB ; BEGIN MINIMUM INITIALIZATION 
FSFAC FBSPUT ; OUTPUT ONLY 


Sample RMS-11 Programs B-5 


FSFNA CRTNAM 
FSFNS CRTNML 
FSLCH 3 
FSORG FBSSEQ 
FSRFM FBSVAR 
FABSE 

CRTNAM: .ASCII /TI:/ 

CRTNML = .-CRTNAM 


se 8 


™e me Ne MO Ne Me Ne 


INPUT RECORD IS SINGLE CHARACTER STRING, 
; THOUGH MOST WILL BE 70 CHARACTERS LONG (MARGINS 0 


me Me we BO Me MO Ne te 


me Ne Ne 


me Ne 


,10.,100.,1000. 


c 

. EVEN 

DOCRAB: RABSB 
RSPAB DOCFAB 
RSMBC 1 
RSMBF 1 
RSRAC RBSSEQ 
RSUBF DOCRCD 
RSUSZ DOCRCL 
RABSE 

e 

CRTRAB: RABSB 
RSFAB CRTFAB 
RSRAC RBSSEQ 
RSROP RBSEOF 
RABSE 

.SBTTL BUFFERS AND MESSAGES 

. PAGE 

; BUFFERS 

t 

DOCRCD: .REPT 80. 
. BYTE 040 
. ENDR 

DOCRCL = .-DOCRCD 

. EVEN 

WDCNT: .WORD 0 

CHRCNT: .WORD 0 

RECLEN: .WORD 0 
.-WORD 0 

XLTBUF: .WORD 1 

PAGENO: .WORD 0 
.- WORD 0 


LINENO: 


f 


; 
? 
? 
; RETURNS 
; 
’ 
; 
; 


FILE NAME ADDRESS 

FILE NAME LENGTH 

LOGICAL CHANNEL FOR FILE 3 
FILE ORGANIZATION 

CRTS ARE VARIABLE 

END INITIALIZATION BLOCK 
ASSUME SYSTEM DEFAULTS 


VARIABLE IN LENGTH 
70). 


BEGIN INITIALIZATION BLOCK 
ADDRESS OF ASSOCIATED FAB 

ONE AT A TIME 

MULTI-BUFFER COUNT 

RECORD ACCESS MODE (S) 

USER RECORD BUFFER ADDRESS 
USER-SET RECORD SIZE 

END INITIALIZATION BLOCK 


BEGIN INITIALIZATION BLOCK 
ADDRESS OF ASSOCIATED FAB 
RECORD ACCESS MODE 


END INITIALIZATION BLOCK 


INPUT RECORD BUFFER 
FILL WITH SPACES 


COUNT WORDS IN FILE 

COUNT CHAR IN RCDS AS DONE 
STORE RCD LENGTH AFTER RMS 
IT 

STOPPER FOR SCAN 

10000.,0 ; POWERS OF 10 
PAGE COUNTER 

LINE COUNTER 


; ARGUMENTS LISTS FOR RMS I/0 OPERATIONS 


DOCLST: .~WORD 
-WORD 
- WORD 
- WORD 


CRTLST: 


; VECTOR TABLES 
CHCODE: .WORD 
-WORD 
-WORD 


1 
DOCRAB 
1 
CRTRAB 


014 
040 
055 
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ue MO Ne Te 


we Me Me 


LENGTH OF ARGUMENT LIST 
RAB FOR RECORD BEING MOVED 
LENGTH OF ARGUMENT LIST 
RAB FOR RECORD BEING MOVED 


FORM FEED 
SPACE 
HYPHEN 


CHCEND = .-CHCODE 
f 
CHPRCS: .WORD FFEED 
-WORD SPACE 
-WORD HYFEN 
»WORD NOTSPA 
c 
-NLIST BIN 
; MESSAGES 
’ 
ERRMSG: .ASCII / ERROR / 
ERRNBR: .ASCII /000000/ ; FILL IN ERROR CODES 
ERRMSL = .-ERRMSG 
BGNMSG: .ASCIZ /START WORDS PROGRAM / 
BGNMSL = .-BGNMSG 
ENDMSG: .ASCIZ /END WORDS PROGRAM / 
ENDMSL = .-ENDMSG 
OPNMSG: .ASCII /RNO.DOC OPENED/ 
OPNMSL = .-OPNMSG 
FFMSG: .ASCII /PAGE / 
FFMSL = .-FFMSG 
WDMSG: .ASCIZ / WORDS IN THIS LINE. TOTAL WORDS = rd 
WDMSL = .-WDMSG 
LINMSG: .ASCII /LINE IS TOO LONG./ 
-ASCIZ / CONTINUING WITH NEXT LINE./ 
LINMSL = .-LINMSG 
BLKS3: .ASCIZ / / 
e 
FILID: .ASCIZ /FILE/ 
DOCID: .ASCIZ /DOC / 
STVID: .ASCIZ /STV / 
~-oBTTL MACROS 
» PAGE 
- LIST BIN 
’ 
; MACROS 
Ul 
»-MACRO MOVWD A,B,?C 
MOV A,R2 ; MOVE STRING A TO THE AREA 
; DESIGNATED BY B, COUNTING THE 
MOV B,R3 ; CHARACTERS AS YOU GO 
CLR Rl ; INITIALIZE COUNTER 
C: MOVB (R2)+,(R3)+ ; MOVE ONE CHARACTER 
INC Rl ; COUNT IT 
CMPB 0, (R2) ; CHECK NEXT SOURCE WORD CHAR 
BNE Cc ; GO BACK FOR MORE IF NOT ZERO 
- ENDM 
-MACRO XLT28 A,B ; 16-BIT NBR TO OCTAL ASCII 
MOV RO,-(SP) ; STORE RO AWAY 
MOV 5,R0 ; 5 IS NBR OF CHARS IN BFR 
MOV A,R1l ; PUT IN NBR 
MOV B,R2 ; MOVE IN RCV BFR 
ADD 6,R2 ; MOVE TO END OF RCV BFR 
JSR PC, XLT8 ; DO IT 
MOV (SP)+,R0 ; BRING RO BACK FROM THE STACK 
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B-8 


- ENDM 


f 
»-MACRO xXLT210 A,B ; 16-BIT NBR TO DECIMAL ASCII 
MOV RO,-(SP) ; SAVE REGISTER ON STACK 
MOV Rl1,-(SP) ; SAVE REGISTER ON STACK 
MOV R2,-(SP) ; SAVE REGISTER ON STACK 
MOV R3,-(SP) ; SAVE REGISTER ON STACK 
MOV R4,-(SP) ; SAVE REGISTER ON STACK 
MOV R5,-(SP) ; SAVE REGISTER ON STACK 
MOV A,RO ; PUT IN NUMBER 
MOV B,R5 ; LOCATION OF 1ST BYTE RCV BFR 
JSR PC, XLT10 ; TRANSLATE IT 
MOV (SP)+,R5 ; GET REGISTER BACK FROM STACK 
MOV (SP)+,R4 3; GET REGISTER BACK FROM STACK 
MOV (SP)+,R3 ; GET REGISTER BACK FROM STACK 
MOV (SP)+,R2 ; GET REGISTER BACK FROM STACK 
MOV (SP)+,Rl ; GET REGISTER BACK FROM STACK 
MOV (SP)+,R0 3; GET REGISTER BACK FROM STACK 
- ENDM 
td 
~-MACRO WRTOUT A,B ; OUTPUT MSG AND LENGTH 
MOV R4,-(SP) ; PUT RAB REFERENCE ON STACK 
MOV R5,-(SP) ; OUT ARG LIST REF ON STACK 
MOV CRTRAB,R4 ; PUT CRT RAB REFERENCE IN R4 
SSTORE A, RBF,R4 ; MSG NAME IN RAB FLD 
SSTORE B,RSZ,R4 ; PUT MSG LENGTH IN RAB FLD 
MOV CRTLST,R5 ; PUT CRT ARG LIST IN R5 
SPUT ; WRITE MESSAGE TO CRT 
MOV (SP)+,R5 ; POP OFF ORIGINAL ARG LIST 
MOV (SP)+,R4 ; POP OFF ORIGINAL RAB REF 
« ENDM 
-SBTTL MAIN PROGRAM 
» PAGE 
; INTERNAL SPACE POOL 
t 
. EVEN 
POOLSB ; BEGIN INITIALIZATION 
PSBDB 2 ; NBR = 
; MAXBUF(1/SEQ)+MAXREL (0)+ (2*MAXIDX (0) ) 
PSBUF 1024, : = 
+ DOC-STREAM-SIZE + CRT-STREAMS-SIZE 
; DOC-STREAM-SIZE = 
+ BKS(1) * (512*MBC(1)) * MBF(1) = 512 
3; CRT-STREAM-SIZE = 
; BKS(1) * (512*MBC(1)) * MBF(1) = 512 
PSFAB 2 ; FAB FOR EACH FILE 
PSRAB 2 ; TWO SEQUENTIAL FILES 
POOLSE 3; END INITIALIZATION AREA 
e 
; RMS FUNCTIONS NEEDED 
v 
ORGS SEQ,<GET,PUT,FIN> ; SEQ FILE GETS, PUT, FINDS 
; Prrtbyrybt)ttr) RUN - TIM BE Plrb_rrrre)ddrrrdrrbddddl 
a 
. EVEN 
START: SINIT ; INITIALIZE RMS 
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=e 


28: 


4s 


me te 


=e 


8S: 


? 
GETLIN 


RO 


a 
= 
ou i 


R2 
R3 


wa 
& 
fou 


R5 


me me Me Ne we MH Ne MO Me 


DOWORD 


~e 


4$ 


me 


8S: 


SOPEN CRTFAB 
MOV CRTFAB,R4 
SCOMPARE 0,STS,R4 
BGT 25 

JMP FILERR 
SCONNECT CRTRAB 
MOV CRTRAB,R4 
SCOMPARE 0,STS,R4 
BGT 4$ 

JMP FILERR 


WRTOUT BGNMSG,BGNMSL 


SOPEN DOCFAB 
MOV DOCFAB,R4 
SCOMPARE 0,STS,R4 
BGT 8$ 

JMP FILERR 


WRTOUT OPNMSG, OPNMSL 
SCONNECT DOCRAB 


MOV DOCRAB,R4 
SCOMPARE 0,STS,R4 
BGT GETLIN 

JMP FILERR 
MOV DOCRAB,R4 
MOV DOCLST,R5 
JSR PC, INPUT 


POINTER TO INPUT LINE 


me Me Me NO Ne 


=e “Oe MO MO Ne 


=e 


me TO MO MO Ne 


me te NO Me Ne 


me Te te 


OPEN CRT 

SET BLOCK TO LOOK AT 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 


HOOK UP CRT 

SET BLOCK TO LOOK AT 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 


OUTPUT IT 


OPEN INPUT FILE 

SET BLOCK TO LOOK AT 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 


HOOK UP INPUT FILE 

SET BLOCK TO LOOK AT 
CHECK OUT STATUS FIELD 
GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 


DOCERR GETS RIGHT CODE 
DOC FILE ARG LIST 
GET RECORD FROM DOC FILE 


CHARACTERS/WORD COUNTER (TO HANDLE MULTIPLE SPACES) 


WORDS/LINE COUNTER 


VECTOR OFFSET INTO TABLE 


DOCRAB 
DOCLST 

CLR Rl 

CLR R3 

INC CHRCNT 

CMP CHRCNT, RECLEN 
BGT 12$ 

CMPB CHCODE (R3) , (RO) 
BEQ 8S 

TST (R3)+ 

CMP R3, CHCEND 
BLT 4S 

JSR PC, @CHPRCS (R3) 
INCB (RO)+ 


OS a 


me me 


™e ue Me Ne Ne 


“=e 


INITIALIZE CHAR/WORD COUNTER 
INITIALIZE VECTOR OFFSET 
CNT CHAR BEFORE LOOK AT IT 


PAST END OF INPUT RCD YET? 
IF SO, GO FINISH UP 


CHECK ON NEXT CHAR IN LINE 
PROCESSING IF EQUAL 
INCREMENT VECTOR 

NOT IN TABLE? 

CHECK NEXT ONE 


DO RIGHT THING 
MOVE TO NEXT CHARACTER 
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BR DOWORD 


12S: CMP 0,R1 
BEQ 168 
INC R2 

16$: CMP 0,R2 
BEQ 18$ 
ADD R2,WDCNT 


XLT210 R2,WDMSG 
XLT210 WDCNT,WDMSG+38. 
WRTOUT WDMSG,WDMSL 
MOVWD BLKS 3,WDMSG 


~e Ne Ne Ne 


18$: JMP GETLIN 
; 
-SBTTL SUBROUTINES 
. PAGE 
? a nd 
; SUBROUTINES 


INPUT: SGET 
SCOMPARE 0,STS,R4 


BGT 2$ 
JMP DOCERR 
f 

2$: SCOMPARE 0,RSZ,R4 
BEQ INPUT 
MOV RECLEN, R3 
SFETCH (R3),RSZ,R4 
BR 8S 


~e Se Me 


6$: MOV R4,-(SP) 
MOV R5,-(SP) 
MOV CRTRAB,R4 


SSTORE DOCRCD, RBF,R4 
SSTORE RECLEN,RSZ,R4 


MOV CRTLST,R5 
SPUT 
MOV (SP)+,R5 
MOV (SP)+,R4 
8S: MOV DOCRCD, RO 

CLR R2 
CLR CHRCNT 
INC LINENO 
RTS PC 

7 

c 

FFEED: INC PAGENO 
CLR LINENO 


XLT210 PAGENO,FFMSG+5. 
WRTOUT FFMSG,FFMSL 
MOV Sopa 

2$: SFIND 
SCOMPARE 0,STS,R4 
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we te Ne Se Me Me TO Ne Ne Ne NO 


~se Ne TO Ne Se eT i ee ee al Md) 


me we TA Ne Ne MO OMS 


ANY CHARACTERS MOVED? 
NOT A REAL LAST WORD 
COUNT LAST WORD 

ANY WORDS IN THIS LINE? 
IF NOT, DON'T DO ANYTHING 
ADD THIS LINE TO TOTAL 
PUT CURRENT LINE IN MSG 
PUT TOTAL CURRENT IN MSG 
OUTPUT IT 

COVER UP LAST WORD COUNT 
GO BACK FOR NEXT LINE 


GET RECORD FROM INPUT FILE 
CHECK OUT STATUS FIELD 

GO AROUND IF NO ERROR 
ERROR CODE(S) AND QUIT 


RECORD LENGTH = 0? 

IF SO, GO GET ANOTHER ONE 
ADDRESS IN REGISTER 

XFR RCD LEN TO BBFR 
BYPASS WRITE OUT 


SPECIAL CASE OF WRTOUT HERE BECAUSE OF RECLEN 


PUT RAB REFERENCE ON STACK 
OUT ARG LIST REF ON STACK 
PUT CRT RAB REFERENCE IN R4 
PUT MSG NAME IN RAB FLD 

PUT MSG LENGTH IN RAB FLD 
PUT CRT ARG LIST IN R5 
WRITE MESSAGE TO CRT 

POP OFF ORIGINAL ARG LIST 
POP OFF ORIGINAL RAB REF 


ADDR OF 1ST CHAR TO RO 

INITIALIZE WORD COUNTER 
INITIALIZE CHAR COUNTER 
COUNT LINE/RECORD 


ADD ONE TO PAGE NUMBER 
RESET LINE NUMBER 

TURN IT INTO DECIMAL 
ANNOUNCE FORM FEED 
FIND CTR TO TOP OF TEXT 
MOVE PAST A LINE 

CHECK OUT STATUS FIELD 


; 
; 
NOTSPA: 


7 
HYFEN: 


we te 


SPACE: 


4S; 


me 


XLT8: 


me Me Me 


f 
XLT10: 
2S: 


BGT 
MOV 
JMP 
SOB 
JSR 
DECB 
CLR 


RTS 


INC 
RTS 


CMP 
BNE 
MOV 
JSR 


MOV 
DECB 
CLR 


RTS 


CMP 
BEQ 
CLR 
INC 
RTS 


MOV 
BIC 
ADD 
MOVB 
ASR 
ASR 
ASR 
SOB 


BIC 
ADD 
MOVB 
RTS 


MOV 
TST 
BEQ 
CMP 
BHIS 


4$ 
(SP)+,RO 
DOCERR 
R3,2$ 
PC, INPUT 
RO 

Rl 


PC 


Rl 
PC 


CHRCNT, RECLEN 
NOTSPA 
R2,-(SP) 

PC, INPUT 


me Ne TO MO me TO Ne NO Ne 


=e “Oe 


we MO Me tO 


GO AROUND IF NO ERROR 

PULL RTN ADDR OFF STACK 
ERROR CODE(S) AND QUIT 

SUB ONE AND BRNCH IF <> 0 
READ NEXT RECORD 

FOR COMMON INCREMENT 

GET RID OF ANY RESIDUAL THAT 
CAN COUNT WORD 

PROCESS IT 


COUNT IT 
LOOK AT NEXT CHARACTER 


LAST CHARACTER IN LINE? 
TREAT IT LIKE ANY OTHER 
CIRCUMVENT INPUT 

BRING IT CONTINUATION LINE 


(DON'T WORRY ABOUT DOUBLE-S PACING 
INPUT THROWS AWAY BLANK LINE) 


v 

; SINCE 
(SP)+,R2 
RO 
Rl 


PC 


0,R1 
4$ 
Rl 
R2 
PC 


R1,-(SP) 


. 
’ 
° 
a 
° 
e 
a 
° 
i 


we MO MO Ne Ne 


BRING WORD COUNT BACK 
ANTICIPATE AUTO INCREMENT 
GET RID OF ANY RESIDUAL THAT 
CAN COUNT WORD 

PROCESS IT 


ANY CHARACTERS MOVED? 
NONE WERE 

CLEAR CHAR/WORD COUNTER 
ONE MORE WORD 

DO NEXT ONE 


USE STACK AS SCRATCH PAD 


B1111111111111000,@SP ; CLR ALL BUT LAST 3 


'0,@SP 
(SP)+,-(R2) 
Rl 
Rl 
Rl 
RO, XLT8 


. 
Ud 
. 
e 
. 
, 


f 


CHANGE DIGIT TO ASCII 
MOVE CHARACTER INTO BUFFER 
3 PLACES TO THE RIGHT 


LOOP IF MORE DIGITS 


NOW CONVERT LEFTMOST BIT IN OCTAL NUMBER 


B111111111111110,Rl1 ; GET BIT 15 


XLTBUF, R4 
(R4) 

4$ 
RO, (R4)+ 
28 


=e Te Me 


=e “se “ee Ne Se 


CONVERT TO ASCII 
MOVE TO BUFFER 
GO BACK 


POINT TO POWERS OF 10 
END OF TABLE? 

YES 

START YET? 

NO 
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B-12 


. 
’ 


TST 
TST 
BNE 
MOVB 
BR 
MOV 
CLR 
DIV 
ADD 
MOVB 
TST 
BNE 


4S: 


6S: 
8S: 


10$: RTS 


-(R4) 
~ (R4) 
6$ 
"0, (R5)+ 
10$ 
RO,R3 
R2 
(R4) ,R2 
'0,R2 
R2,(R5)+ 
~(R4) 
8$ 


PC 


; 
-SBTTL ERROR ROUTINES 
- PAGE 


=e 


, 
. 
Ul 
. 
f 
. 
' 


ERROR ROUTINE 


i 
FILERR: MOVWD 


FILERI1: 


SFETCH 
XLT 28 
WRTOUT 
SCOMPARE 
BEO 
MOVWD 
SFETCH 
MOV 
XLT 28 
WRTOUT 
MOV 
MOV 
CLR 
SOB 


4S: 


- LIST ME 


XLT210 


»NLIST ME 


Wwe se we 


OCERR: 


WRTOUT 
DUN: EXITSS 
ERROR 


SCOMPARE 
BEQ 
SCOMPARE 
BEQ 
MOVWD 
JMP 

XLT 210 
WRTOUT 
WRTOUT 
BR 


28: 


A i eT eT OT i a a et a | 


ue 


BACK UP TABLE 

DITTO 

NON-ZERO NUMBER TO PRINT 
PRINT A ZERO 

ALL DONE 

MOVE NBR IN PREP FOR DIVIDE 
MORE PREP FOR DIVIDE 
DIVIDE BY POWER OF 10 
MAKE QUOTIENT A CHARACTER 
INSERT IN RCV BUFFER 

GET ANOTHER POWER OF 10 
NO THRU YET 


GO HOME WHEN DONE 


FOR FILE OPERATIONS AND DOC FILE AND CRT 


FILID, ERRMSG 
R2,STS,R4 
R2,ERRNBR 
ERRMSG, ERRMSL 
0,STV,R4 
DUN 
STVID, ERRMSG 
R2,STV,R4 
R2,-(SP) 
R2,ERRNBR 
ERRMSG, ERRMSL 
(SP)+,R2 
6.,R0 
(RO)+ 
RO, 4$ 


R2, ERRNBR 


ERRMSG, ERRMSL 


ERSEOF,STS,R4 


2$ 


4§ 
DOCID, ERRMSG 
FILER1 


ERSRTB, STS, R4 


WDCNT,WDMSG+38. 
WDMSG+24.,18. 


ENDMSG, ENDMSL 
32$ 
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we me Ne Ne me TO NO me TO Me Me NO 


me 


=e me 


me me Ne Ne TH Ne Te NB Me Ne 


MOVE ERROR CODE IN 

FIGURE NBR; PUT IT IN BFR 
PUT IT OUT 

ANYTHING IN STV? 

GO AROUND IF THERE'S NOT 


MOVE COMPLETION VALUE IN 
SO NO NEED FETCH IT AGN 
FIGURE NBR; PUT IT IN BFR 


BRING BACK STV VALUE 
NBR OF CHAR IN ERRNBR 
ZERO THAT BYTE 

TILL ALL ARE DONE 


MAKE IT A DECIMAL NUMBER 


DISPLAY IT 
QUIT THIS THING 


ROUTINE FOR RECORD OPERATION ON INPUT FILE 


RUN OUT OF RECORDS? 

GO AROUND IF THAT'S IT 
LINE TOO LONG? 

GO AROUND IF THAT'S IT 
IDENTIFY ERROR 

HANDLE LIKE OTHER ERRORS 
PUT TOTAL CURRENT IN MSG 
OUTPUT IT 

PUT IT ON SCREEN 

GO TO END 


PUT IN LINE NUMBER 
DISPLAY MSG 


4$: XLT210 LINENO, LINMSG+5. 
WRTOUT LINMSG, LINMSL 


; 
; 
JMP INPUT ; GET NEXT RECORD (PC IS GOOD 
; "CAUSE NOT LEFT SUBRTN) 
32S: EXITSS ; QUIT IT 


? 
-END START 
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B. 


3. TESTING RELATIVE FILE CAPABILITIES 


This sample program creates a Relative file, sets up a Record Access 


Stream, and runs five tests: 
l. Test if can put a record with a relative record number greater 
than the Maximum Record Number set for the file. 
2. Test if can get records past the Maximum Record Number set for the 
file. 
3. Test if sequential get operations retrieve only valid records. 
4. Test if sequential get operations retrieves deleted records. 
5. Test if approximate match tests (KGE and KGT) work during random 
get operations. 
-MCALL SINIT,FABSB,NAMSB, XABSB,RABSB, ORGS, POOLSB 
-MCALL SGNCAL,SFBCAL, SRBCAL, SSTGDPLY, SGETSTG, EXITSS 
SGNCAL 
SFBCAL 
SRBCAL 
i 
; POOL SPACE 
; 
POOLAR: 
POOLSB 
PSBDB 6 
PSFAB 2 
PSRAB 2 
PSBUF 4608. 
POOLSE 
; FAB AREA 
7 
. EVEN 
FABAR: 
FABSB ;ALLOCATE FAB 
FSBKS 2 ;BUCKET SIZE 
FSFAC FBSGET! FBSPUT!FBSDEL ;DOING GETS AND PUTS 
FSFOP FBSTMD ;THIS FILE TO BE DELETED 
FSLCH 1 ;USE LOGICAL CHANNEL 1 
FSMRS 80. 7;MAX RECORD SIZE OF 80 
FSORG FBSREL ;RELATIVE FILE 
FSRFM FBSVAR ; VARIABLE LENGTH RECORDS 
FABSE 
; 
7 RAB AREA 
. EVEN 
RABAR: 
RABS$B ;ALLOCATE RAB 
RSFAB FABAR ;POINTS TO FAB AREA 
RSKBF KEYNO ;WHERE TO PUT RELATIVE KEY NUMBER 
RSKSZ 4 ;KEY IS 4 BYTES 
RSRAC RBSSEQ ;WRITE RECORDS SEQUENTIALLY 
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RSRBF RECBUF ;ADDR OF RCD PUT OR GOT 


RSUBF RECBUF ;SAME AS RBF 
RSUSZ 150. 
RABSE 
; 
; 
. EVEN 
FABTI: 
FABSB 
FSFAC FBSPUT ;PUT TO THE FILE 
FSFNA TFNAM ;TERMINAL FILE NAME 
FSFNS TFNAMS ;TERMINAL FILE NAME SIZE 
FSFOP FBSCTG! FBSTMD ;CONTIGUOUS SPACE, TEMP FILE 
FSLCH 2 ;LOGICAL CHANNEL 2 
FSMRS 768. ;MAX REC SIZE = 768. BYTES 
FSORG FBSSEQ ;SEQUENTIAL FILE 
FSRAT FBSCR ;RECS DELIMITED BY CR AND LF 
FSRFM FBSFIX ;FIXED FORMAT RECS 
FABSE 
t 
RABTI: 
RABSB 
RSFAB FABTI ;PILE CTRL BLOCK ADDR 
RSRAC RBSSEQ ;SEQUENTIAL ACCESS 
RSUBF BUFTI ;USER BUFFER ADDR 
RSUSZ 80. ;MAX SIZE = 80. BYTES 
RABSE 


LOCAL SYMBOLS 


me es Ne 


CR = 15 ;ASCII CARRIAGE RETURN 
LF = 12 ;ASCII LINE FEED 
; 
PRAMTR: .~BLKW 1 ;PARAMETER TO SEND INFO TO PRINT 
; 
HOLDIT: .BLKB 2 ;HOLD NUMBER FOR ASCII CONVERT 
KEYNO: .BLKB 4 ;RELATIVE KEY 
KEYTST: .BLKB 2 ;KEYTST TO COMPARE RECORD RETRIEVED 
WITH RECORD PUT 
DELTST: .BLKB 2 ;TEST FOR DELETED RECORDS 
TSTFOR: .BLKB 1 ;TO TEST FOR FOURTH TEST 
ERR: - BLKB 1 ;TEST FOR TEST 4 ERRORS 
RNFSET: .BLKB 1 ;TEST FOR RNF ERROR 
; 
.- EVEN 
; 
BUFTI: .BLKB 80. ;TERMINAL FILE BUFFER 


e 
RECBUF: 
RECKEY: .BLKW 2 
-ASCII /MISC. DATA/ <CR><LF> 
RECLEN = . - RECBUF 


; 
TFNAM: .ASCII /TI:RELTST.ERR/ ;TERMINAL FILE NAME 
TFNAMS = - ~ TFNAM 


° 


. 
r 
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‘ 
MSGTBL: 


ERR1: 
ERRI1LN 


7 
ERR2: 
ERR2LN = 


7 
ERR3: 
ERR3LN = 


’ 
ERR4: 
ERR4LN = 


, 

MSG5: 
TESTNO: 
SuUC5: 
MSG5LN = 


ERR6: 
ERR6LN = 


7 
ERR7: 
DELNUM 


ERR7LN = 


7 

ERR8: 
ERR8LN = 
ERRY: 
ERROLN = 


ERR1O: 
ERI1OLN = 


ERR11: 
ER11LN = 


ERR12: 
ER12LN = 


’ 

ERR13: 
FINDNO 
CRLF13 
ER13LN = 


ERR14: 
ER14LN = 


f 

ERRI5: 
TST5NO: 
CRLF15: 
ERI5LN = 


7 
ERR16: 


-ASCII /ERROR CREATING TTY FILE/ <CR><LF> 
=. - ERR1 


-ASCII /ERROR CONNECTING TTY FILE/ <CR><LF> 
- — ERR2 


-ASCII /ERROR CREATING RELATIVE FILE/ <CR><LF> 
- — ERR3 


-ASCII /ERROR CONNECTING RELATIVE FILE/ <CR><LF> 
- — ERR4 


-ASCII /TEST / 

. BLKB 2 

-ASCII / SUCCESSFUL!/ <CR><LF> 
- ~ MSG5 


-ASCII /ERROR PUTTING RECORD TO FILE/ <CR><LF> 


-ASCII /ERROR DELETING RECORD NUMBER / 
. BLKB 

eASCII <CR><LF> 

- 7 ERR7 


-ASCII /ERROR GETTING RECORD FROM FILE/ <CR><LF> 
- - ERR8 


-ASCII /ERROR CLOSING FILE/ <CR><LF> 
- — ERRQ 


-ASCII /ERROR REWINDING FILE/ <CR><LF> 
- — ERR1O 


-ASCII /ERROR DISCONNECTING FILE/ <CR><LF> 
- ~ ERR11 


-ASCII /RETRIEVED WRONG RECORD IN FILE/ <CR><LF> 
- ~ ERR12 


-ASCII /ERROR FINDING RECORD NUMBER / 
- BLKB 4 

-ASCII <CR><LF> 

- - ERR13 


-ASCII /ERROR - OVER 40. RECORDS WRITTEN ON TEST1/ <CR><LF> 
» ~ ERR14 


-ASCII /DID NOT GET RECORD NUMBER / 


- WORD 1 
»ASCII <CR><LF> 
- ~ ERRI15 


-ASCII /ERROR DISCONNECTING FILE/ <CR><LF> 
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ER16LN = . — ERR16 


- EVEN 

ERRTBL: .WORD ERRI1 
-WORD ERRILN 
-WORD ERR2 
-WORD ERR2LN 
-WORD ERR3 
-WORD ERR3LN 
-WORD ERR4 
- WORD ERR4LN 
-WORD MSG5 
- WORD MSG5LN 
-WORD ERR6 
- WORD ERR6LN 
-WORD ERR7 
- WORD ERR7LN 
- WORD ERR8 
-WORD ERR8LN 
-WORD ERRQ 
- WORD ERR9OLN 
-WORD ERR1O 
- WORD ER1OLN 
«WORD ERR11 
-WORD ER11ILN 
-WORD ERR12 
- WORD ER12LN 
-WORD ERR13 
-WORD ER13LN 
-WORD ERR14 
-WORD ER14LN 
»WORD ERR15 
-WORD ER15LN 
-WORD ERR16 
» WORD ER16LN 


ORGS REL, <CRE, FIN, GET, PUT, DEL> 
ORGS SEQ,<CRE, PUT> 
START: 
SINIT 
JSR PC, CRETTY ;CREATE, CONNECT TTY FILE 
JSR PC, CREATE ;CREATE, CONNECT RELATIVE FILE 
JSR PC; TESTI ;TEST 1 BEGINS 
JSR PC, TEST2 ;TEST 2 BEGINS 
JSR PC, CLOSE ;DISCONNECT AND CLOSE FILE 
JSR PC, TEST3 ;TEST 3 BEGINS 
JSR PC, TEST4 ;TEST 4 BEGINS 
JSR PC, TESTS ;TEST 5 BEGINS 


me 


Sample RMS-11 Programs B-17 


JSR PC, CLOSE 
EXITSS 

7 

;CREATE AND CONNECT THE TTY FILE 

CRETTY: 
MOV 0, PRAMTR 
SCREATE FABTI, ENDIT 
MOV 4, PRAMTR 
SCONNECT RABTI, ENDIT 
RTS PC 

c 

;CREATE THE RELATIVE FILE 

CREATE: 
MOV RABAR, R4 
SSTORE RECLEN,RSZ,R4 
CLR Rl 
MOV 40.,RO 
MOV FABAR, R5 
SSTORE RO,MRN,R5 
MOV 10, PRAMTR 
SCREATE R5, ENDIT 
RTS PC 

CONECT: 
MOV 14, PRAMTR 
MOV RABAR,R5 
SCONNECT R5, ENDIT 
RTS PC 

td 

;REWIND THE FILE 

t 

REWIND: 
MOV 44, PRAMTR 
SREWIND RABAR, ENDIT 
RTS PC 

, 

;DISCONNECT AND CLOSE THE FILE 

af 

CLOSE: 
MOV 74,PRAMTR 
SDISCONNECT RABAR, 
MOV 40, PRAMTR 
SCLOSE FABAR, ENDIT 
RTS PC 


PRINT THE MESSAGES 


e ™e Ne 


’ 

PRINT: 
MOV 0,R2 
MOV PRAMTR, R2 
ADD ERRTBL, R2 
MOV RABTI,R3 
SSTORE (R2),RBF,R3 
SSTORE 2(R2),RSZ,R3 
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;DISCONNECT AND CLOSE FILE 


7;SET UP TTY CREATE ERRMSG 
;CREATE TTY FILE 

;SET UP TTY CONNECT ERR 
;CONNECT TTY FILE 


; INITIALIZE RAB POINTER 
;SET UP RECORD SIZE 

7;RO R1 SET UP 2 WORD MRN 
*SET UP RO FOR MRN 

7;SET UP FAB POINTER 

; INITIALIZE 40. AS MRN 

;SET UP CREATE REL FILE ERR 
;CREATE THE FILE 


7;SET UP CONNECT REL FILE ERR 
;SET UP RAB POINTER 
;CONNECT REL FILE 


;SET UP FOR REWIND ERROR 
7GO TO B-O-F FOR NEXT TEST 


7;SET UP FOR DISCONNECT ERROR 


ENDIT ;DISCONNECT FILE 


;SET UP FOR CLOSE ERROR 
;CLOSE FILE 


;CLEAR R2 

;SET UP INDEX WITHIN TABLE 
POINTER TO ERROR MESSAGE 
7;POINTER TO ERROR TABLE 
;STORE ADDRESS OF MESSAGE 
;STORE SIZE OF MESSAGE 


SPUT R3,BOMB ;TTY MSG - BOMB ON ERROR 


RTS PC 
tf 
ENDIT: 
JSR PC, PRINT ;PRINT ERROR MESSAGE 
BOMB: 
BPT ;BOMB 
; 
a ae en er eee a eee ee 
;TEST 1 
; THIS IS A TEST OF MRN. MRN SET TO 40. 
; WILL ATTEMPT TO WRITE 50. RECORDS. 
3 SHOULD ENCOUNTER ERSMRN ERROR. 
td 
; 
TEST1l: 
CLR Rl ; INITIALIZE Rl 
JSR PC, CONECT ;CONNECT THE FILE 
PUTIT: 
INC Rl ;NEXT RECORD 
SPUT R4 ;WRITE THE RECORD 
SCOMPARE SUSSUC,STS,R4 ;PUT ERROR? 
BNE T1ERR ;IF YES, GO TO TI1ERR 
CMP 50.,Rl ;WRITTEN 50 RECORDS YET? 
BHI PUTIT ;NO, GO WRITE SOME MORE 
MOV 64, PRAMTR ;SET UP FOR TEST 1 ERROR 
JSR PC, ENDIT ;PRINT ERROR MESSAGE, BOMB 
T1ERR: 
MOV 24,PRAMTR ;SET UP FOR PUT ERROR 
SCOMPARE ERSMRN,STS,R4 ;MRN ERROR? 
BNE ENDIT ;NOT MRN ERROR--BOMB 
MOV 20, PRAMTR ;SET UP FOR SUCCESS MSG 
MOV 61, TESTNO ;SET UP FOR PRINTING TEST 1 
JSR PC, PRINT ;PRINT SUCCESS MESSAGE 
JSR PC, REWIND ;RETURN TO B-O-F 
RTS PC ;GO ON TO TEST 2 


=e 


‘ 

; IF TEST 1 IS SUCCESSFUL, RECORDS HAVE BEEN WRITTEN 
; UP TO MRN. THAT IS, 40 RECORDS HAVE BEEN WRITTEN. 
; THE FILE HAS BEEN REWOUND, READY FOR TEST 2. 


’ 
f 
; THIS TEST ATTEMPTS TO RETRIEVE RECORDS 
; SEQUENTIALLY BEYOND MRN. 

: SHOULD ENCOUNTER AN ERSEOF ERROR. 

; IT ATTEMPTS TO RETRIEVE 50., RECORDS. 

; AFTER THE 40.TH RECORD, AN ERSEOF ERROR 
; SHOULD RESULT. 


a i ee ee ne ew ee ee ee ee we ee ae a a ae ee a ae a we ee ee 
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MOV RABAR, R4 7;SET UP RAB POINTER 


CLR R1 ; INITIALIZE RECORD COUNTER 
MOV 34, PRAMTR ;SET UP FOR GET ERROR 
MOV 62, TESTNO ;SET UP FOR PRINTING TEST 2 
T2INC: 
INC R1 ; INCREMENT RECORD COUNTER 
SGET RABAR ;GET ANOTHER RECORD 
SCOMPARE SUSSUC,STS,R4 ;SUCCESSFUL GET? 
BNE GETERR ;IF NOT, GO TO GETERR 
CMP 50.,R1 ;GOTTEN 50 RECORDS YET? 
BNE T2INC ;IF NOT, CONTINUE 
RTS PC ;YES, RETURN 
GETERR: 
SCOMPARE ERSEOF,STS,R4 ;EOF ERROR? 
BNE ENDIT ;NOT AN EOF ERROR - BOMB 
MOV 20,PRAMTR ;SET UP FOR TEST SUCCESS MESSAGE 
JSR PC, PRINT ;PRINT SUCCESS MESSAGE 
JSR PC, REWIND ;GO TO BEGINNING OF FILE 
RTS PC ;GO ON TO NEXT TEST 
: 
piece se tee eee eee eee ee ere a eee 
;TEST 3 
; CREATE A NEW FILE. 
; PUT EVERY OTHER RECORD RANDOMLY UP TO AN MRN OF 40. 
; REWIND, AND GET SEQUENTIALLY. 
; SHOULD GET ONLY THOSE RECORDS JUST PUT. 
mesdesees se eehe ss Soe el ee ea eee eee te 
f 
TEST3: 
JSR PC , CREATE ;CREATE NEW RELATIVE FILE 
SSTORE RBSKEY,RAC,R4 ;RELATIVE ACCESS MODE 
JSR PC ,CONECT ;CONECT THE FILE 
MOV 1,KEYNO ;INITIALIZE THE RELATIVE KEY 
CLR KEYNO+2 ;CLEAR 2ND WORD OF KEY 
CLR RECKEY+2 ;CLEAR 2ND WD OF KEY IN FILE 
e 
;SET UP FILE - WRITE EVERY OTHER RECORD 
c 
SETUP: 
MOV 24,PRAMTR ;SET UP FOR PUT ERROR 
MOV KEYNO, RECKEY ;PUT KEY NUMBER IN RECORD 
SPUT RABAR, ENDIT ;PUT RCD; ERROR = MSG, END. 
ADD 2, KEYNO ;SKIP A RECORD 
CMP 40. ,KEYNO ;PILE FULL? 
BHI SETUP ;IF NOT, WRITE SOME MORE 
MOV 20,PRAMTR ;SET UP FOR TEST 3 SUCCESS 
MOV 63, TESTNO ;SET UP FOR PRINTING TEST 3 
; #*keke Ae COMMON ROUTINE FOR TESTS 3 AND 4 **#**keeeH 
i 
;REWIND AND REINITIALIZE 
c 
SEQGET: 
CALL REWIND ;RETURN TO BEGINNING OF FILE 
MOV -1,KEYTST ;SET UP TO TEST FOR CORRECT RCD 


SSTORE RBSSEQ,RAC,R4 ;GET SEQUENTIALLY 
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i 
;GET THE RECORDS SEQUENTIALLY 


a 
GETIT: 
SGET R4 ;GET RECORD 
SCOMPARE SUSSUC,STS,R4 ;SUCCESSFUL GET? 
BNE GETERR ;1F NOT, TEST FOR E-O-F 
;GETERR IN TEST 2 
RECTST: 
ADD 2,KEYTST ;EVERY OTHER RECORD 
CMP KEYTST, RECKEY ;RIGHT RECORD? 
BEQ GETIT ;IF SO, LET'S GET ANOTHER 
BADREC: 
CMPB 1, TSTFOR ;IS IT TEST 4? 
BNE BADCON ;IF NOT, WRONG RCD 
ADD 6,DELTST ;HOLD KEY OF NXT DELETED RCD 
CMP DELTST, KEYTST ;IS IT A DELETED RECORD? 
BEQ RECTST ;YES, ADD 2 TEST AGAIN 
BADCON: 
MOV 54, PRAMTR ;WRONG RECORD = MSG 
IMP ENDIT ;PRINT OUT MESSAGE, BOMB 
tA 
ee ee en ae ea 
;TEST 4 
: TEST 4 USES THE FILE CREATED IN TEST 3. 
; SOME RECORDS ARE DELETED. 
; GET SEQUENTIALLY AND SEE IF DELETED RECORDS 
; ARE FOUND. 
TEST4 
MOV RABAR,R4 ;SET UP RAB POINTER 
SSTORE RBSKEY,RAC,R4 ;DELETE USING RANDOM 
MOV -5,KEYNO ;INIT REL KEY FOR DELETES 
MOV 1,TSTFOR ;SET UP FOR FOURTH TEST 
MOV -5,DELTST ;INIT FOR DELETED RCD KEY 
NXTDEL: 
ADD 6, KEYNO ;DELETE EVERY 4TH RECORD 
JSR PC, FINDIT 7GO DELETE IT 
CMP 37. ,KEYNO ;LAST RECORD 
>TO BE DELETED BEFORE EOF? 
BHI NXTDEL ;IF NOT, DELETE SOME MORE 
CMPB 0, ERR ;ANY ERRORS ENCOUNTERED? 
BEQ GET4 ;NO ERRORS, GET SEQUENTIALLY 
JMP BOMB ;ERRORS FOUND —- BOMB 
GET4: 
MOV 20, PRAMTR ;SET UP FOR TEST 4 SUCC MSG 
MOV 64, TESTNO ;SET UP FOR PRINTING TEST 4 
JSR PC,SEQGET ;READY TO GET SEQUENTIALLY 
RTS PC ;GO ON TO NEXT FILE 
FINDIT: 
SFIND RABAR 
SCOMPARE SUSSUC,STS,R4 ;FIND SUCCESSFUL? 
BEQ DELETE ;IF IT WAS, DELETE RECORD 
MOV 60, PRAMTR ;SET UP FOR FIND ERROR 
MOV KEYNO, RO ;SET UP FOR KEY NO. 
;CONVERSION TO ASCII 
JSR PC, CONVER ;CONVERT RCD NBR TO ASCII 
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MOV HOLDIT, FINDNO ;PUT RCD NBR IN ERRMSG 
JSR PC, PRINT ;PRINT ERROR MESSAGE 
RTS PC 7GO ON TO NEXT RECORD 
DELETE: 
SDELETE RABAR ;DELETE RECORD 
SCOMPARE SUSSUC,STS,R4 ;SUCCESSFUL DELETE? 
BEQ RETURN ;IF SUCCESSFUL, CONTINUE 
MOV 30,PRAMTR 7SET UP FOR DELETE ERRMSG 
MOV KEYNO, RO 7;SET UP FOR ASCII CONVERT 
CALL CONVER 7;CNV KEY NBR TO ASCII FOR ERRMSG 
MOV HOLDIT, DELNUM 7;PUT RCD NBR IN ERRMSG 
JSR PC, PRINT ;PRINT ERROR MESSAGE 
‘ 
RETURN: 
RTS PC 7;GO ON TO NEXT RECORD 


; 
7;CONVERSION TO ASCII TO PRINT OUT RCD NBR IN ERRMSG 


a 
CONVER: 
MOVB 1, ERR ;NOTE THAT ERROR OCCURRED 
MOV RABAR, R4 ;SET UP RAB PNTR AFTER ERR 
SSTORE 1,STS,R4 ;RESET TO GOOD STATUS 
MOV 1,R3 ;SET UP R3 FOR INDEXING 
MOV 2,R2 ;SET UP R2 TO LOOP 2 TIMES: 
s;ONCE FOR EACH BYTE 
LOOP: 
MOV RO,- (SP) ;SAVE REMAINDER FOR CNV 
BIc -10,R0 :CLEAR ALL BUT LOW ORDER 3 BITS 
ADD 60,R0 ;CONVERT TO ASCII 
MOVB RO, HOLDIT (R3) ;STORE IT IN RECORD 
MOV (SP)+,RO0 ;GET COUNTER 
ASR RO ;SHIFT RIGHT 3 BITS 
ASR RO 7;TO WORK ON EACH DIGIT 
ASR RO 
DEC R3 ;MOVE TO NXT BYTE OF RECKEY 
SOB R2, LOOP ;DIGIT IN EACH BYTE?? 
RTS PC 


, 

c 

; THIS TEST WILL TEST THE ROP FIELDS OF 

; KGT AND KGE. 

; AFTER SUCCESSFUL COMPLETION OF TEST 4, 

; THE FILE WILL NOW HAVE OCTAL RECORDS: 

: 37 5,711,13,17, 21, 25,27 33; 35,41,43,47. 

; USING THIS INFORMATION, WE WILL TEST 

; "KEY GREATER THAN' AND 'KEY GREATER THAN 
; OR EQUAL TO'. 


MOV RABAR, R4 7;SET UP RAB POINTER 
SSTORE RBSKEY,RAC,R4 ;USING RANDOM 
SSTORE RBSKGT,ROP,R4 ;SET UP KEY GREATER THAN 


JSR 
SSTORE 


PC, KGT 
RBSKGE, ROP, R4 
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;DO KEY GREATER THAN TEST 
;SET UP KEY GTR'N OR = TO 


GOOD5: 


KGT: 


KGE: 


GETS5: 


GT5ERR: 


COMPAR: 


JSR 
JSR 
CMPB 
BEQ 
RTS 


MOV 
MOV 
CALL 
RTS 


MOV 
MOV 
JSR 
MOV 
MOV 
CALL 
MOV 
MOV 
JSR 
MOV 
MOVB 
JSR 
RTS 


MOV 
MOV 
JSR 
MOV 
MOV 
CALL 
MOV 
MOV 
CALL 
MOV 
MOV 
JSR 
RTS 


SGET 
SCOMPARE 
BEQ 

CMPB 

BNE 

MOVB 
SCOMPARE 
BNE 

RTS 


MOV 
SSTORE 
MOVB 
JSR 
RTS 


CMP 
BNE 


PC, REWIND 
PC, KGE 

0, ERR 
GOOD5 
PC 


65, TESTNO 
20, PRAMTR 
PRINT 
PC 


5, KEYNO 
11,R0 
PC,GET5 
20,KEYNO 
21,R0 
GET5 
27,KEYNO 
33,R0 
PC,GETS 
47, KEYNO 
1, RNFSET 
PC, GETS 
PC 


5,KEYNO 
5,R0 
PC,GET5 
20,KEYNO 
21,RO0 
GETS 
27,KEYNO 
27,RO 
GET5 
47,KEYNO 
47,RO 
PC,GET5 
PC 


R4 


SUSSUC,STS,R4 


COMPAR 

1, RNFSET 
GT5ERR 

0, RNFSET 


ERSRNF,STS,R4 


GT5ERR 
PC 


34, PRAMTR 
1,STS,R4 
1, ERR 
PC, PRINT 
PC 


RO, RECKEY 
ERROR5 


7;GO TO BEGINNING OF FILE 
;DO KEY GTR'N OR = TEST 
;ANY ERRORS DETECTED? 
;NO ERRORS = SUCCESS MSG 


;MOV 5 INTO SUCCESS MESSAGE 
;SET UP FOR TEST 5 SUCC MSG 
;PRINT MESSAGE 

;DONE WITH TEST 5 


;WE WANT THE NEXT REC GT 5 
;IT SHOULD BE RECORD 11 
7GET THE RECORD 
;TRY NEXT REC GTR'N 20 
;WE SHOULD GET RECORD 21 
7;GET THE RECORD 

;WANT THE NEXT REC GTR'N 27 
;WE SHOULD GET RECORD 33 
;GET THE RECORD 

;GET REC GT 47 
;SET UP TO TEST FOR RNF 
;SHOULD GET RNF ERROR 

7GO ON TO KGE TEST 


;WE WANT THE REC. GE 5 
;SHOULD GET RECORD 5 
;GET THE RECORD 

;WE WANT THE REC. GE 20 
;WE SHOULD GET RECORD 21 
;GET THE RECORD 

;WE WANT THE REC. GE 27 
;SHOULD GET RECORD 27 
;GET THE RECORD 

;WE WANT THE REC. GE 47 
;SHOULD GET RECORD 47 
;GET THE RECORD 

;DONE WITH TEST 5 


;GET THE RECORD 

;SUCCESSFUL GET? 

7YES = TEST FOR CORRECT RCD 

7;TESTING FOR RNF ERROR? 

;NO = CONT ERR PROCESSING 

;RESET FOR NO RNF ERROR 

;DID WE GET AN RNF ERROR? 
;NO, THERE'S REALLY AN ERROR 
;RNF ERR = GOOD, CONTINUE 


;SET INDEX FOR GET ERR 
;RESET TO GOOD STATUS 
;SET ERR BYTE 

;PRINT GET ERROR MESSAGE 


;CORRECT RECORD? 
;IF NOT GO TO ERROR ROUTINE 
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RTS 


ERRORS: 


ue 


B-24 


MOV 
JSR 
MOV 
CALL 
RTS 


- END 


PC 


70,PRAMTR 
PC, CONVER 
HOLDIT, TST5NO 
PRINT 

PC 


START 
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7WE DID, CONTINUE 


;SET INDEX IN TABLE FOR ERROR MSG 
7;CNV RCD NBR TO ASCII FOR PRINT 
;PUT RCD NBR IN MSG 

;PRINT THE MESSAGE 


me me Me Me Se te Me MO Ne Ne me Me Me te Ne NP Ne Te Me Ne te NO NO 


APPENDIX C 


DATE CONVERSION ROUTINE 


-TITLE SCDTTA - CONVERT DATE AND TIME TO ASCII 
~-IDENT "x0001" 


COPYRIGHT (C) 1977 BY DIGITAL EQUIPMENT CORPORATION, 
COPYRIGHT (C) 1976 BY DIGITAL EQUIPMENT CORPORATION, 
MAYNARD, MASSACHUSETTS 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE IN- 
CLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DIGITAL. 


THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITH- 
OUT NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY 
DIGITAL EQUIPMENT CORPORATION. 


DIGITAL EQUIPMENT CORPORATION ASSUMES NO RESPONSIBILITY FOR 
THE USE OR RELIABILITY OF ITS SOFTWARE ON EQUIPMENT WHICH IS 
NOT SUPPLIED BY DIGITAL. 


ANDREW C. GOLDSTEIN 20 JUN 76 14:12 
SMACIT 


-MACRO SSAVRG 
JSR R5,S5SAVRG 
. ENDM SSAVRG 


-MACRO .QUAD WORD 
$$$B1=0 
$$$B2=0 
$$$B3=0 
$SSB4=0 
SSSB5=0 
SSSB6=0 
$$$B7=0 
SSSB8=0 


; SOME 


ONS: 


OND: 


FDAYS 


CDAYS 
QDAYL 
QDAYH 
DS15L 
DS15H 


C-2 


. IRPC D,WORD 
S$S$B1=SSSB1*10.+D'. 
SSSC=$S$B1/256. 
$$$B1=$$$B10377 
$SSB2=SSSB2*10.+$S$C 
$$$C=SS$SB2/256. 
$$$B2=S$$B20377 
$SSB3=$$$B3*10.+$SSC 
$$$C=S$$B3/256. 
$$$B3=$$$B 30377 
SSSB4=SSSB4*10.+SSSC 
SS$C=S$$B4/256. 
$S$B4=$$$B40377 
$SSB5=SS$SB5*10.+SSSC 
$$S$C=S$$B5/256. 
$SS$B5=$$$B50377 
SSSB6=$S$B6*10.+SSSC 
$$$C=$SSB7/256. 
$S$B6=$$$B60377 
$$SB7=SSSB7*10.+5SSC 
SS$SC=SSSB7/256. 
$$$B7=$$$B70377 
SSSB8=SSSB8*10.+SSSC 
$$$C=SSSB8/256. 
$$$B8=$$$B 80377 

. ENDM 


S$$SSW1=S$$B2*256. 
SSSW2=SS$SB4*256. 
-+SSSB5 


SS$SW3=$$$B6*256 


+SS$B1 
+$S$B3 


S$SSW4=S$$$B8*256.+SSSB7 
. LIST MEB 

.WORD $$swl,$ssw2 
. WORD $$Sw3,SSsw4 
-NLIST MEB 

. ENDM . QUAD 
CONSTANTS 

»-RADIX 10 

. QUAD 10000000 
.WORD $$$w1,S$$sw2 
. WORD $$Sw3,SSsw4 
. QUAD 864000000000 
. WORD SSSw1,S$$Sw2 
.WORD $$$w3,SSSw4 
365*441 

FDAYS*25-1 

15025 

2 

65176 

1 


Date Conversion Routine 


we Ne Ne 38 8 Me Ot 


TENTHS OF MICROSECONDS IN A SECOND 


TENTHS OF MICROSECONDS IN A DAY 


NUMBER OF DAYS IN 4 YEARS 

AND NUMBER OF QUARTER DAYS IN A YEAR 
NUMBER OF DAYS IN A CENTURY 

NUMBER OF DAYS IN QUADRICENTURY, LOW 
NUMBER OF DAYS IN QUADRICENTURY, HI 
NUMBER OF DAYS BETWEEN 1-JAN-1501 
AND 17-NOV-1858, LOW AND HIGH 


-RADIX 


+ 


*** — SCDTTA CONVERT DATE/TIME TO ASCII 


THIS ROUTINE CONVERTS THE STANDARD DATE/TIME REPRESENTATION INTO 
AN ASCII STRING. THE FORMATTING OF THE STRING IS CONTROLLED BY 
OPTION BITS ON INPUT. 


INPUTS: 
RO = ADDRESS TO STORE ASCII STRING 
Rl = ADDRESS OF 64 BIT DATE/TIME 
R2 = OPTION FLAGS: 
BIT 0 = 1 IF DATE NOT WANTED 
BIT 1 = 1 IF TIME NOT WANTED 
BIT 2 = 1 IF TIME WANTED IN AM/PM 
BIT 3 = 1 IF SECONDS NOT WANTED 
OUTPUTS: 


RO UPDATED TO END OF GENERATED STRING 
OTHER REGISTERS PRESERVED 


THE DATE ALGORITHM BELOW ACCOUNTS FOR THE COMMON LEAP YEAR CYCLES - 
EVERY FOURTH YEAR IS, EXCEPT EVERY 100TH ISN'T, EXCEPT EVERY 400TH 
IS. YEAR 2000 IS A LEAP YEAR. THE CODE IS BASED ON ALGORITHMS 
WRITTEN BY P.CONKLIN, J.BARNABY, D.ROSENBERG, AND M.SPEIR. 


me Me te Ne TO Te Me Ne TO Ne TO Ne Se Ne NS Ne Ne SO ME MO NO Ne Te Ne NH Ne MO Ne NO 


SCDTTA:: 
SSAVRG : SAVE ALL REGISTERS 
MOV R1,-(SP) 
MOV R2,-(SP) 
MOV RO,R5 
SUB #16.,SP . ALLOCATE TWO QUAD SLOTS 
MOV SP,R3 
ADD #8.,R3 
MOV #OND,RO ; SPLIT DATE/TIME INTO DAY AND TIME 
MOV SP,R2 
JSR PC, SDIVQ 


TOP OF STACK CONTAINS DAYS SINCE 17-NOV-1858. CONVERT THIS TO A 
REAL DATE. 


“se se te we 


BIT #1,16. (SP) ; DO OF DATE REQUESTED 

BNE LO 

MOV (SP) ,R3 ; DAY SINCE 17-NOV-1858 IS 

MOV 2(SP),R2 ; LESS THAN 32 BITS 
; ADD THE OFFSET SO WE HAVE THE NUMBER 
; OF DAYS SINCE 1-JAN-1501, ALIGNING 
7; CYCLES SO THAT THE LATER 
;  TRUNCATIONS AND ROUND-OFFS WORK. 

ADD #DS15L,R3 

ADC R2 

ADD #DS15H,R2 
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me te MOA we we MO Ne 


we Ne TO Ne 


c-4 


MOV 
MOV 
JSR 


ASL 
ASL 
MOV 
ASL 
ROL 
ASL 
ROL 
MOV 
MOV 


MOV 
MOV 
JSR 


ADD 


#QDAYH, RO 
#QODAYL,R1 
PC, SDIVD 


#QODAYH, RO 
#ODAYL,R1 
Pc, SDIVD 


R3, (SP) 


=e Ne 


we Ne Ne 


eae Ne Ne NO 


=e 


oe me Ne 


BY BASING THE TIME AT 1501, 


INTO THE FIRST CENTURY OF THE QUADRICENTURY. 


DIVIDE BY THE NUMBER OF DAYS IN 
A QUADRICENTURY 


RO,R1 = DAYS INTO THIS QUADRICENTURY 
R3 = QUADRICENTURIES SINCE 1501 
CONVERT TO CENTURIES 


AND SAVE 

CONVERT NUMBER OF DAYS INTO 
NUMBER OF QUARTER DAYS 

BY MULTIPLYING BY 4 


DIVIDE BY THE AVERAGE NUMBER OF 
QUARTER DAYS IN A CENTURY 


RO,R1 = QUARTER DAYS INTO CENTURY 
R3 = CENTURIES IN THIS QUAD CENTURY 
ADD TO ACCUMULATED TIME 


THE CENTURY HAS AN EXTRA LEAP DAY 


NOW DISCARD ANY 


FRACTION OF A DAY LEFT FROM THE PREVIOUS DIVISION AND ADD IN 3/4 
OF A DAY TO FORCE THE LEAP YEAR INTO THE LAST YEAR OF EACH 4 YEAR 


CYCLE. 


BIS 
MOV 
MOV 
MOV 
MOV 
JSR 
MOV 
ASR 
ASR 
INC 
MOV 
MOV 
JSR 
ADD 
ADD 
MOV 


FIND OUT WHETHER THIS YEAR 


#3,R1 
R1,R3 
RO,R2 
#0,RO 
#FDAYS,R1 
PC, SDIVD 
R1,R2 

R2 

R2 

R2 
#100.,RO0 
(SP)+,R1 
PC, SMULUS 
R3,Rl1 
#1501.,R1 
R1,-(SP) 


IT IS PAST FEBRUARY: 


MOV 
MOV 
MOV 
JSR 
TST 
BNE 


#1,R4 
(SP) ,RO 
#400.,R1 
PC, SDIV 
Rl 

Ll 


ue =e Ne 


=e 


e 
a 


. 
’ 


IS A LEAP YEAR. 


NOW DIVIDE BY THE AVERAGE NUMBER OF 
QUARTER DAYS IN A YEAR 


NUMBER OF DAY IN YEAR 


COMPUTE # YEARS IN CENTURIES 


COMPUTE TRUE CALENDAR YEAR 
SAVE FOR FINAL OUTPUT 


IF NOT, BIAS THE DAY IF 


THE MONTH TABLE IS WRITTEN FOR A LEAP YEAR. 


° 
f 
° 


a 


° 
’ 
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INIT LEAP YEAR FLAG TO NO 
EVERY 400TH IS A LEAP YEAR 


FROM SYSLIB 


CLR R4 
BR L2 
Ll: 
MOV (SP) ,RO . 
MOV #100.,R1 
JSR PC, SDIV ; 
TST Rl 
BEQ L3 
MOV (SP) ,RO A 
MOV #4,R1 
JSR PC, SDIV . 
TST Rl 
BNE L4 
CLR R4 
L4: 
L3: 
L2: 
7 
7 
a 
CMP R2, #31.428. 
BLOS L5 
ADD R4,R2 
L5:; 
e 
; SCAN THE MONTH TABLE AND FIND 
CLR Rl 
BO: 
MOVB SDAYTB(R1),RO ; 
CMP R2,RO0 
BLOS E0 
SUB RO,R2 
INC Rl 
CMP R1l,#11. 
BLT BO 
EO: 
tf 
; R2 = DAY, R1 = MONTH 
; START TO CRANK OUT THE ASCII 
‘ 
MOV R1,-(SP) 
MOV R5,R0 : 
MOV R2,Rl 
MOV #0,R2 
JSR PC ,SCBDMG 
MOVB #'-, (RO)+ ; 
MOV (SP) ,R1 
ASL Rl 
ADD (SP)+,R1 
ADD #SMONTB,R1 
MOVB (R1)+ ; 
MOVB (R1)+, (RO)+ 
MOVB (R1)+, (RO)+ 
MOVB #'-, (RO)+ : 
MOV (SP)+,R1 H 


EVERY 100TH IS NOT 


FROM SYSLIB 


AND EVERY 4TH IS 


FROM SYSLIB 


IF THIS IS NOT A LEAP YEAR, 
BIAS THE DAY UP ONE IF IT IS 
PAST FEBRUARY. 


OUT WHAT MONTH THIS IS. 


GET NUMBER OF DAYS IN MONTH 


DATE 


DAY NUMBER 


DASH 


INDEX INTO THE MONTH NAME TABLE 


FILL IN MONTH NAME 


DASH 
ADD YEAR 
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MOV 
JSR 
MOVB 
MOV 


me Se Me 


BIT 
BNE 
MOV 
ADD 
MOV 
SUB 
MOV 
MOV 
JSR 
MOV 
MOV 
CMP 
MOV 
MOV 
JSR 
MOV 
MOV 
JSR 
MOV 
MOV 
JSR 


MOV 
JSR 
MOVB 
MOV 
JSR 
MOV 
BIT 
BNE 
MOVB 
JSR 
L7: 
MOV 
L6: 
ADD 
MOV 
MOV 
RTS 


+ 


#4 — C2D 


INPUTS: 


ee eT a TY 


RO = 
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#0,R2 
PC, SCBDMG 
#40, (RO)+ 
RO,R5 


#2,16. (SP) 
L6 


SP,Rl 
#8.,R1 
SP,R3 
#8.,SP 
#ONS,RO 
SP,R2 
PC, SDIVO 
(SP)+,R3 
(SP)+,R2 
(SP)+, (SP)+ 
#0,RO0 
#60.,R1 
PC, SDIVD 
R1,-(SP) 
#60.,R1 
PC, SDIVD 
Rl,-(SP) 
#24.,R1 
PC, SDIVD 


R1,RO 

PC, C2D 
#':,(R5)+ 
(SP)+,RO 
PC, C2D 
(SP)+,RO 
#10,16. (SP) 
LZ 


#':,(R5)+ 
Pc ,C2D 


R5,RO 


#16.,SP 
(SP)+,R2 
(SP)+,R1 
PC 


° 
i 
e 
a 


’ 


. 
’ 


. 
c 


=e 


=e 


=e 


~e 


=e Ne 


=e 


=e 


AND A SPACE 
SAVE THE POINTER WHILE WE MESS 
WITH THE TIME OF DAY 


NOW CONVERT THE TIME OF DAY TO ASCII 


DO IF TIME REQUESTED 

POINT TO TIME ON STACK 

ALLOCATE ONE MORE QUAD 

REDUCE TO TIME IN SECONDS 

WHICH IS EXPRESSIBLE IN 32 BITS 
CLEAN GARBAGE FROM STACK 

DIVIDE OUT SECONDS 

AND SAVE THEM 

DIVIDE OUT MINUTES 


AND SAVE 
AND DIVIDE OUT HOURS 


OUTPUT ASCII TIME OF DAY 


GET SECONDS 
IF SECONDS WANTED 


RETURN FINAL STRING POINTER 


FINAL STACK CLEANUP 


CONVERT BINARY TO 2 DECIMAL DIGITS 


BINARY VALUE 


THIS ROUTINE IS USED TO OUTPUT THE COMPONENTS OF THE TIME 


CQ 0 we te Me Ne Ne SO Ne 


+ 


me we MO Ne Ne Ne Me MO Se MO Ne Ne Ne Ne MH Ne MO NS Me Te Ne me Ne MO Me NO SO Ne Me 


OUTPUTS: 


TWO DIGITS STORED AT R5 
R5 BUMPED BY 2 
RO,R1 CLOBBERED 


MOV #10.,R1 ; 
JSR PC,SDIV : 
ADD #'0,RO : 
ADD #'0,R1 

MOVB RO, (R5)+ : 
MOVB Rl, (R5)+ 

RTS PC 


SPLIT THE DIGITS 
FROM SYSLIB 
CONVERT TO ASCII 


AND STORE 


*** — SDIVD DOUBLE PRECISION DIVIDE 


THIS ROUTINE PERFORMS AN UNSIGNED DIVIDE WITH 32 BIT DIVISOR, 


DIVIDEND, QUOTIENT, 


ANDREW C. 


AND REMAINDER. 


DIVIDE BY ZERO IS NOT CHECKED. 


GOLDSTEIN 4 MAR 76 11:41 


BASED ON THE ALGORITHM IN RT-11'S LIBRARY ROUTINE JDIV 


INPUTS: 
RO = HIGH ORDER DIVISOR 
Rl = LOW ORDER DIVISOR 
R2 = HIGH ORDER DIVIDEND 
R3 = LOW ORDER DIVIDEND 
OUTPUTS: 
RO = HIGH ORDER REMAINDER 
Rl = LOW ORDER REMAINDER 
R2 = HIGH ORDER QUOTIENT 
R3 = LOW ORDER QUOTIENT 


R4,R5 PRESERVED 


SDIVD:: 


MOV R4,-(SP) ; 
MOV R5,-(SP) 
MOV #33.,-(SP) ; 
CLR R4 ; 
CLR R5 i 
: ROL R5 ; 
ROL R4 
CMP RO,R4 ; 
BHI 30$ ; 
BNE 20$ ; 
CMP R1,R5 ; 


SAVE R4 R5 


SET UP ITERATION COUNT 
QUOTIENT ENDS UP IN R2:R3 
REMAINDER ENDS UP IN R4:R5 
EXPOSE NEW BIT OF NUMERATOR 


DOES DENOM FIT? 
BRANCH IF NOT, C=0 
BRANCH IF YES 


HIGH PARTS SAME, CHECK LOW 
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208 


30$ 


St i BT i TT i eT i i el el lt a et en eal) 


SDI 


BHI 
SUB 
SBC 
SUB 
SEC 
: ROL 
ROL 
DECB 
BGT 
TST 
MOV 
MOV 
MOV 
MOV 
RTS 


30$ 
R1,R5 
R4 
RO, R4 


R3 
R2 
(SP) 
10$ 
(SP)+ 
R4,R0 
R5,Rl 
(SP)+,R5 
(SP)+,R4 
PC 


me Ne 


me te we te 


BRANCH IF NOT, C=0 
SUBTRACT DENOM FROM REMAINDER 


INDICATE NEW QUOTIENT BIT 
SHIFT IN NEW BIT OF QUOTIENT 


CHECK LOOP COUNT 

BRANCH TO LOOP 

CLEAN THE STACK 

MOVE REMAINDER TO RO Rl 


RESTORE R4 R5 


*** — SDIVQ QUAD DIVIDE ROUTINE 


THIS ROUTINE DOES A 64 BIT UNSIGNED DIVIDE OPERATION. DIVIDE 
BY ZERO IS NOT CHECKED, 
SIGNIFICANCE IN INCREASING ADDRESSED BYTES. 


ANDREW C. 
INPUTS: 


RO 
Rl 
R2 
R3 


OUTPUTS: 


QUOTIENT AND 


VO:: 
CALL 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
MOV 
CLR 
CLR 
CLR 
CLR 


108: MOV 


C-8 


ROL 
ROL 
ROL 
ROL 
MOV 
ADD 
MOV 


Date Conversion Routine 


ALL NUMBERS ARE STORED WITH INCREASING 


GOLDSTEIN 17-NOV-76 10:47 


ADDRESS OF DIVISOR 
ADDRESS OF DIVIDEND 
ADDRESS OF QUOTIENT 


ADDRESS OF REMAINDER 


SSAVAL 
#65.,-(SP) 
R2,R5 
(R1)+, (R5)+ 
(R1)+, (R5)+ 
(R1)+, (R5)+ 
(R1)+, (R5)+ 
R3,R4 

(R4)+ 

(R4)+ 

(R4)+ 

(R4)+ 

R3,R4 

(R4)+ 

(R4)+ 

(R4)+ 

(R4)+ 

RO,R1 
#8.,R1 
R4,R5 


me Ne Ne 


=e 


Bry 


=e 


me Me 


REMAINDER RETURNED IN SPECIFIED ADDRESSES 


SET UP LOOP COUNT 
POINT TO QUOTIENT AREA 
COPY DIVIDEND INTO QUOTIENT AREA 


COPY REMAINDER POINTER 
CLEAR OUT REMAINDER AREA 


R4 POINTS TO END OF REMAINDER 


SHIFT IN NEXT BIT OF DIVIDEND 


POINT TO HIGH ORDER OF DIVISOR 
AND OF REMAINDER AREA 


CMP ~(R1),-(R5) ; SEE IF DIVISOR IS GREATER THAN 
BNE 20$ ; CURRENT REMAINDER VALUE 
CMP -(R1),-(R5) 
BNE 20$ 
CMP -(R1),-(R5) 
BNE 20$ 
CMP -(R1),-(R5) 
208: BHI 30$ ; YES: BRANCH, NO SUBTRACT, C IS CLEAR 
MOV RO,R1 ; POINT TO START OF DIVISOR 
MOV R3,R4 ; AND START OF REMAINDER 
SUB (R1)+, (R4)+ ; SUBTRACT DIVISOR FROM REMAINDER 
SBC (R4)+ 
SBC (R4)+ 
SBC (R4) 
CMP ~(R4),-(R4) 
SUB (R1)+, (R4)+ 
SBC (R4) 
SBC 2(R4) 
SUB (R1)+,(R4)+ 
SBC (R4) 
SUB (R1)+,(R4)+ 
SEC ; SET BIT TO SHIFT INTO QUOTIENT 
308: MOV R2,R5 ; POINT TO QUOTIENT 
ROL (R5)+ ; SHIFT NEW BIT IN FROM RIGHT 
ROL (R5)+ 
ROL (R5)+ 
ROL (R5)+ ; C = NEXT BIT OF DIVIDEND 
DEC (SP) ; COUNT ITERATIONS 
BNE 10$ ; AND LOOP 
TST (SP)+ ; CLEAN THE STACK 
RTS PC 
SMULUS:: MOV RO,-(SP) 
MOV #21,-(SP) 
CLR RO 
108: ROR RO 
ROR Rl 
BCC 20$ 
ADD 2(SP) ,RO 
20S: DEC @SP 
BGT 10$ 
CMP (SP)+,(SP)+ 
RETURN 
. END 
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INDEX 


16-bit signed integer key type, 5-36 
16-bit unsigned binary key type, 5-36 
32-bit signed integer key type, 5-36 
32-bit unsigned binary key type, 5-36 
64-bit date, 5-23 
Abnormal close, unlock file if, 3-29 
Access by RFA, 4-19 
Access fields in user control blocks, 1-2 
Access mode during record operation, 4-19 
Access mode, random, 4-19 
Access mode, sequential, 4-19 
Add blocks to an RMS-11 file, 8-10 
Address, lower, 7-1 
Address, Record's File, 4-19, 4-22, 8-19, 8-23 

and disk files, 8-20, 8-24 
Advantage of different bucket sizes, 5-12 
Allocate user control blocks, 1-2 
Allocation information, 1-13 
Allocation options, 5-10 
Allocation quantity, 5-8 

maximum, 3-4 

minimum, 3-4 

(See also Allocation XAB ALQ field) 

(See also FAB ALQ field) 
Allocation XAB 

AID, 5-3t, 5-4 

ALN, 5-3t, 5-6 

ALQ, 5-3t, 5-8 

ALQ field and current extent, 5-9 

AOP, 5-3t, 5-10 

BKZ, 5-3t, 5-11 

BLN, 5-3t, 5-13 

COD, 5-3t, 5-14 

completely optional, 5-2 

DEQ, 5-3t, 5-15 

DEQ is zero, 3-18 

internal structure of Indexed file, 5-2 

LOC, 5-3t, 5-17 

NXT, 5-3t, 5-19 

placement control, 5-2 

sequencing of, 5-4 

VOL, 5-3t, 5-20 
Allocation, contiguous, 3-28, 5-10 


Index-l 


Allocation, hard, 5-10 
ALQ. (See File Access Block) 
ANSI magnetic tape, 3-24 
Approximate match, 4-13 
Area, 1-13, 5-2, 5-4. (See also Allocation XAB) 
containing index Level 0, 5-31 
containing index Level 1, 5-48 
containing index Levels 2+, 5-41 
maximum number, 5-4 
maximum number in an Indexed file, 5-74 
minimum number, 5-4 
number in an Indexed file, 5-74 
summary of keys and, in an Indexed file, 5-71 
Area number 
data, 5-31 
index, 5-41 
lowest index level, 5-48 
Maximum, 5-31, 5-41, 5-48 
Area, fixed control, 3-32 
maximum, 3-32 
minimum, 3-32 
Argument list 
address of, 1-21 
contents, 1-21 
RMS-11 generates, 1-21 
your program supplies, 1-20 
ASCII, conversion of eight-byte date to, 5-23 
Assemble, 1-2 
command string, 1-22 
Astrophysical base date, Smithsonian, 5-23, 5-26 
Asynchronous record operation, 1-22, 4-25 
outstanding, 8-33 
wait for, 8-33 
Attribute information, 1-2 
Attributes in XAB fields, store file, 8-6 
Attributes of an RMS-11l file, retrieve, 8-12 
Attributes, record, 3-44 
Automatic file extension, 5-15 
failure of, 3-18 
(See also File Access Block DEQ field) 
(See also Allocation XAB DEQ field) 
Available for processing, existing file, 8-12 
Backward, move magnetic tape file forward or, 9-6 
Base date, Smithsonian astrophysical, 5-23, 5-26 
BASIC+, 5-26 
Beginning of a file, logical, 8-29 
BID. (See File Access Block) 
Binary key type 
16-bit unsigned, 5-36 
32-bit unsigned, 5-36 
Bit string data field 
reset bits within a, 7-6 
set bits within a, 7-7 
Bits within a bit string data field 
reset, 7-6 
set, 7-7 
Bits within a field with your value, compares, 7-11 
Bits, least significant, 7-1 
BKS. (See File Access Block) 


Index-2 


BRT. (See Record Access Block) 
BLN. (See Record Access Block) 
Block boundaries, cross, 3-45 
Block fields, retrieve modify and test, 7-l 
Block header formats, RMS-11 pool, 2-10 
Block I/0, 9-1 
cautions, 9-1 
SREAD, 3-23, 9-2t, 9-3 
SREAD and ERSEOF error code, 9-4 
SREAD and multiple blocks, 9-3 
SREAD and unit record terminators, 9-4 
required procedure, 9-1 
SSPACE, 9-2t, 9-6 
virtual block number, 4-4 
SWRITE, 3-24, 9-2t, 9-5 
SWRITE and multiple blocks, 9-5 
SWRITE and partial blocks, 9-5 
Block number 
logical, 3-48, 5-7 
maximum virtual, 4-4 
Root virtual, 5-59 
virtual, 3-48, 5-7, 5-38 
Block size, magnetic tape. (See File Access Block BLS field) 
maximum magnetic tape, 3-10 
minimum magnetic tape, 3-10 
recommended sizes, 3-9 
Block spanning, 3-44 
Block, characters in magnetic tape. (See File Access Block) 
Block, Release Core. (See GSA routine) 
Block, Request Core. (See GSA routine) 
Block, retrieve a specified virtual, 9-3 
Block, user control. (See user control block) 
Block, write a specified virtual, 9-5 
Blocks to an RMS-11 file, add, 8-10 
BLS. (See File Access Block) 
Boundaries, cross block, 3-45 
BPA. (See File Access Block) 
BPT instruction, A-18 
Bucket fill number 
data, 5-34 
index, 5-44 
Bucket size, 4-17, 5-9, 5-11, 5-16, 5-49 
advantage of different, 5-12 
and default extension quantity, 3-17, 5-15 
and initial allocation quantity, 3-4, 5-8 
data, 5-33 
index, 5-43 
maximum, 3-6, 5-11 
minimum, 3-6, 5-11 
valid for Relative and Indexed files only, 3-6 
(See also FAB BKS field) 
(See also Allocation XAB BKZ field) 
Bucket, calculating number of bytes in a, 5-34, 5-44 
Bucket, first data, 5-38 


Index-3 


Buffer 
allocation, 8-16 
I/O buffer size, 1-6 
record processing use, 1-6 
requirements, 1-7 
RMS-11 control of, 1-6 
user control of, 1-6 
Buffer Descriptor Blocks, 2-lt 
calculating requirements, 2-2 
Buffer pool. (See central buffer pool) 
Buffer pool, private 
address, 3-11 
address on word boundary, 3-11 
and central buffer pool, 3-12 
calculating size of, 3-13 
your program's use of, 3-12 
Buffer size, key, 4-13 
Buffer size, user, 4-34 
and Locate Mode, 4-32 
Maximum, 4-34 
Buffer space. (See central buffer pool) 
optimize, 4-25 
release, 8-18 
Buffer 
I/o, 1-6 
private I/O, 1-6. (See also private buffer pool) 
record header, 4-23 
user, 8-23 
Buffers, writes all modified I/O, 8-21 
Bypass RMS-11 record processing, 9-1 
Bytes in a bucket, calculating number of, 5-34, 5-44 
Calculating number of bytes in a bucket, 5-34, 5-44 
Call error, fatal user, A-18 
Calling sequence, 1-20 
Carriage return control, 3-44 
Central buffer pool 
allocated at assembly time, 2-1 
multiple allocation in modules, 2-1 
requirements, 1-2 
Task Builder, 2-1 
Chain of XABs, 5-19, 5-25, 5-55, 5-67, 5-76 
Changability, 5-39 
Change during update, key, 5-39 
Channel, logical, 3-35 
and Record Access Streams, 3-36 
maximum logical, 3-35 
minimum logical, 3-35 
once assigned, 3-36 
Character, null key, 5-53 
Characteristics, key, 5-39 
and Primary Keys, 5-40 
null key, 5-39 
valid combination of, 5-40 
Characters in magnetic tape block. (See File Access Block) 
SCLOSE. (See macro) 
Close 
an open RMS-11 file, 8-2 
rewind magnetic tape file on, 3-29 
unlock file if abnormal, 3-29 
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Cluster number, device, 5-7 
Clustersize, 3-50 
file extension and, 3-18, 5-16 
maximum, 3-50 
minimum, 3-50 
Code, protection, 5-64 
programmer number, 5-68 
project number, 5-69 
Code, status, 3-54 
Codes, error completion, A-1l 
Codes, success completion, A-1 
SCOMPARE. (See macro) 
Compare field with your value, 7-2 
Compares bits within a field with your value, 7-11 
Completion codes, error, A-l 
Completion codes, success, A-l 
Completion routines, 1-19 
register usage during, 1-20 
return control from, 1-20 
RMS-11 operations within, 1-20 
Conditions, inconsistent internal, A-18 
Conditions, severe error, A-2 
SCONNECT. (See macro) 
Contents of a field to your location, copy the, 7- 
Contents of your location to a field, copy the, 7- 
Context, 1-22 
Context field, user. (See File Access Block CTX field) 
Context, set, 8-29 
at end-of-file during connect operation, 4-25 
Contiguous allocation, 3-28, 5-10 
Continue processing on the next tape volume, 8-25 
Control block, user. (See user control block) 
Control structures, internal, 1-6 
Control, carriage return, 3-44 
Control, FORTRAN forms, 3-44 
Control, placement, 5-6 
RSTS/E restriction, 5-7 
Conversion of eight-byte date to ASCII, 5-23, 5-26 
Copy the contents of a field to your location, 7-4 
Copy the contents of your location to a field, 7-9 
Core Block, Release. (See GSA routine) 
Core Block, Request. (See GSA routine) 
Crash routine, fatal error, A-2 
and general registers, A-18 
ERSBUG error code, A-19 
ERSFAB error code, A-18 
ERSMAP error code, A-19 
ERSRAB error code, A-18 
SCREATE. (See macro) 
Create 
an RMS-1l1 file, 8-4 
an RMS-11l task, 1-22 
Creation date and time information, file, 5-21 
Creation date, file, 5-23 
accuracy of, 5-23 
Criterion, match, 4-13 
Cross block boundaries, 3-45 
CTX. (See File Access Block) 
Current extent and Allocation XAB ALQ field, 5-9 
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Current record, 1-22 
Cylinder number, 5-7 
Data area number, 5-31 
Data bucket fill number, 5-34 
Data bucket size, 5-33 
Data bucket, first, 5-38 
Data field, reset bits within a bit string, 7-6 
Data field, set bits within a bit string, 7-7 
Data type, key, 5-36 
and prologue version number, 5-77 
reassembly requirement, 5-36 
Date and time information 
file creation, 5-21 
file revision, 5-21 
Date-time information, 1-13 
Date to ASCII, conversion of eight-byte, 5-23, 5-26 
Date XAB 
BLN, 5-21t, 5-22 
CDT, 5-21t, 5-23 
COD, 5-21t, 5-24 
NXT, 5-21t, 5-25 
RDT, 5-21t, 5-26 
RVN, 5-21t, 5-27 
Date, 64-bit, 5-23, 5-26 
Date, file creation, 5-23 
accuracy of, 5-23 
Date, file revision, 5-26 
accuracy of, 5-26 
Date, Smithsonian astrophysical base, 5-23, 5-26 
Decimal radix, 1-2, 1-10 
Declare RMS-11 facilities, 1-2 
Default extension quantity, 3-17, 5-15 
for file, 3-18 
maximum, 3-18, 5-15 
minimum, 3-17, 5-15 
when Allocation XAB DEQ fields are zero, 3-18 
(See File Access Block DEQ field) 
(See Allocation XAB DEQ field) 
Default name string, 3-20 
and logical names, 3-21 
contents, 3-20 
maximum, 3-22 
notation, 3-21 
size, 3-22 
Defaults, system, 1-16 
Deferred Write, 3-29 
SDELETE. (See macro) 
Delete 
an existing record, 8-17 
an RMS-11 file, 8-8 (See also S$ERASE) 
fast, 4-25 
file marked for, 3-29 
records from a Sequential file, 8-30 
temporary file marked for, 3-29 
DEQ. (See File Access Block) 
DEV. (See File Access Block) 
Device characteristics. (See File Access Block DEV field) 
Device cluSter number, 5-7 
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Device ID, 1-16 
do not manipulate, 6-2 
used with file ID, 6-2 
Device, unit record, 3-45 
Different bucket sizes, advantage of, 5-12 
Directives, .MCALL, 1-2 
Directory entry(s), remove RMS-ll file's, 8-8 
SDISCONNECT. (See macro) 
Disconnect all Record Access Streams, 8-2 
Disk file size. (See Allocation XAB ALQ field) 
Disk Sequential files and multiblock count, 4-15 
SDISPLAY. (See macro) 
DNA. (See File Access Block) 
Duplicatability, 5-39 
Duplicate key values, 5-39 
Eight-byte date, 5-23, 5-26 
conversion to ASCII, 5-23, 5-26 
End of magnetic tape file, position to, 3-29 
Environment, processing, 1-2 
ERScod, A-1 
ERSISI error code after close operation, 8-3 
ERSWER error code on close operation, 8-3 
SERASE. (See macro) 
Error completion codes, A-1 
Error conditions, severe, A-2 
Error crash routine, fatal, A-2 
and general registers, A-18 
ERSBUG error code, A-19 
ERSFAB error code, A-18 
ERSMAP error code, A-19 
ERSRAB error code, A-18 
Error on relative files, record-exists, 4-26 
Error, fatal user call, A-18 
Establish a Record Access Stream, 8-16 
-EVEN, 1-8, 1-11, 1-13, 1-17 
Exact match, 4-13 
Existing file 
available for processing, 8-12 
supersede, 3-29 
Existing record in an RMS-1l file, replace an, 8-31 
Existing record, delete an, 8-17 
Expanded file name string 
address, 6-3 
length from RMS-ll, 6-4 
size from your program, 6-5 
Explanation of locked file, 3-30 
SEXTEND. (See macro) 
Extended Attribute Block, 1-1, 1-13, 5-1 
allocation macros, 1-3 
Allocation XAB, 1-13, 5-2 
and Indexed files, 3-57 
and the FAB, 3-56 
cautions, 1-14 
chain of, 3-56 
Date XAB, 1-13, 5-21 
extension of FAB, 1-13 
field offset macros, 1-3, 5-1 
initialization, 1-14 
initialization macros, 1-3, 5-1 


Index-7 


Extended Attribute Block (continued) 
Key XAB, 1-13, 5-28 
linking and ordering, 1-14 
ordering by type of XAB, 1-14 
ordering withing XAB type, 1-16 
Protection XAB, 1-13, 5-64 
required during creation, 1-13 
required during display, 1-13 
Summary XAB, 1-13, 5-71 
XBSALL, 1-13 
XBSDAT, 1-13 
XBSKEY, 1-13 
XBSPRO, 1-13 
XBSSUM, 1-13 
Extension and clustersize on RSTS/E, file, 3-18, 5-16 
Extension quantity, default. (See default extension quantity) 
Extension, automatic file, 5-15 
failure of, 3-18 
Extent and Allocation XAB ALQ field, current, 5-9 
FSfnm. (See macro) 
FAB. (See Record Access Block) 
FAC. (See File Access Block) 
Facilities, declare RMS-ll, 1-2 
Failure of automatic file extension, 3-18 
Fast delete, 4-25 
Fatal error crash routine, A-2, A-18 
and general registers, A-18 
ERSBUG error code, A-19 
ERSFAB error code, A-18 
ERSMAP error code, A-19 
ERSRAB error code, A-18 
Fatal user call error, A-18, A-18 
FCS, 5-26 
SFETCH. (See macro) 
Field Access Macros 
#0 and SCOMPARE, 7-2 
SCOMPARE, 7-lt, 7-2 
SFETCH, 7-lt, 7-4 
SFETCH and KEY XAB SIZ/POS field, 7-4 
SOFF, 7-lt, 7-6 
SSET, 7-lt, 7-7 
SSTORE, 7-lt, 7-9 
SSTORE and KEY XAB SIZ/POS field, 7-9 
STESTBITS, 7-1t, 7-11 
Field 
compare with your value, 7-2 
compares bits within to your value, 7-11 
copy the contents of your location to a, 7-9 
copy the contents to your location, 7-4 
key, 5-28 
set bits within a bit string data, 7-7 
reset bits within a bit string data, 7-6 
user context. (See File Access Block CTX field) 
Fields 
access at run time, 1-18 
access macros, 1-18. (See also Field Access Macros) 
in user control blocks, access, 1-2 
modify contents, 1-18, 7-6, 7-7, 7-9 
proper values before operation, 1-8, 1-11, 1-13 
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Fields (continued) 
retrieve contents, 1-18, 7-4 
retrieve, modify, and test block, 7-1 
RMS-11 changes default during operations, 1-19 
store file attributes in XAB, 8-6 
test contents, 1-18, 7-11 
user control block. (See user control block) 
File Access Block, 1-1, 1-8, 3-1 
allocation, 1-8 
allocation macros, 1-3 
ALQ, 1-9t, 3-2t, 3-3 
associated with a RAB, 8-16 
BID, 1-9t, 3-5 
BKS, 1-9t, 3-2t, 3-6 
BKS vs. XAB BKZ, 5-9 
BLN, 1-9t, 3-2t, 3-8 
BLS, 1-9t, 3-2t, 3-9 
BPA, 1-9t, 3-2t, 3-1 
BPS, 3-2t, 3-13 
cautions, 1-10 
CTX, 1-9t, 3-2t, 3-16 
DEQ, 1-9t, 3-2t, 3-17 
DEQ vs. XAB DEQ, 3-18, 5-16 
DEV, 1-9t, 3-2t, 3-19 
DNA, 1-9t, 1-16, 3-2t, 3-20 
DNS, 1-16, 3-2t, 3-22 
FAC, 1-9t, 3-2t, 3-23 
field offset macros, 1-3, 3-1 
FNA, 1-9t, 1-16, 3-2t, 3-25 
FNS, 1-9t, 1-16, 3-2t, 3-27 
FOP, 1-9t, 3-2t, 3-28 
FSZ, 1-9t, 3-2t, 3-32 
IFI, 1-9t, 3-2t, 3-34 
initialization, 1-9 
initialization macros, 1-3, 3-l 
KSZ, 3-2t 
LCH, 1-9t, 3-2t, 3-35 
MRN, 1-9t, 3-2t, 3-37 
MRS, 1-9t, 3-2t, 3-39 
NAM, 1-9t, 3-2t, 3-41 
ORG, 1-9t, 3-2t, 3-43 
RAT, 1-9t, 3-2t, 3-44 
representing more than one file, 1-8, 4-8 
RPM, 1-9t, 3-2t, 3-46 
RTV, 1-9t, 3-2t, 3-48, 3-50 
SHR, 1-9t, 3-2t, 3-52 
STS, 1-9t, 3-2t, 3-54 
STV, 1-9t, 3-2t, 3-55 
XAB, 1-9t, 3-2t, 3-56 
File Address, Record's, 4-19, 4-22, 8-19, 8-23 
and disk files, 8-20, 8-24 
File attributes in XAB fields, store, 8-6 
File available for processing, existing, 8-12 
File contents unavailable, 8-2 
File creation date, 5-23 
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accuracy of, 5-23 
File creation date and time information, 5-21 
File default extension quantity, 3-18 
File extension 
and clustersize on RSTS/E, 3-18, 5-16 
automatic, 5-15 
failure of automatic, 3-18 
File forward or backward, move magnetic tape, 9-6 
File ID, 1-16, 3-29 
do not manipulate, 6-6 
used with device ID, 6-6 
File marked for delete, 3-29 
File marked for delete, temporary, 3-29 
File name string 
address, 3-25 
conform to system standards, 3-26 
notation, 3-25 
parsing under RSTS/E, 3-26 
size, 3-27 
use in file specification, 3-25 
File name string size, maximum, 3-27 
File name string, expanded 
address, 6-3 
length from RMS-11, 6-4 
size from your program, 6-5 
File on close, rewind magnetic tape, 3-29 
File on open, rewind magnetic tape, 3-29 
File opened for write operations by RMS-1l, 5-27 
File operation, 1-2, 1-19 
calling sequence, 1-20 
FAB associated with the macro, 8-1 
RMS-11 verifies FAB before, 3-5, 3-8 
RMS-11 verifies XAB before, 5-13, 5-14, 5-22, 5-24, 5-29, 5-30, 
5-65, 5-66, 5-72, 5-73 
valid, 3-23 
File Operation Macros, 1-21, 8-1 
SCLOSE, 1-22t, 8-lt, 8=2 
SCLOSE and ERSISI error code, 8-3 
SCLOSE and ERSWER error code, 8-3 
SCLOSE and I/O request, 8-2 
SCLOSE and NAM Block, 8-3 
SCLOSE buffer requirements, 8-2 
SCREATE, 1-22t, 8-lt, 8-4 
SCREATE and Allocation XABs, 8-4 
SCREATE and NAM Block, 8-4 
SCREATE buffer requirements, 8-4 
SDISPLAY, 1-22t, 8-lt, 8-6 
SDISPLAY buffer requirements, 8-6 
SERASE, 1-22t, 8-lt, 8-8 
SERASE buffer requirements, 8-8 
SERASE by file ID, 8-8 
SERASE while file is open, 8-9 
SEXTEND, 1-22t, 8-lt, 8-10 
SEXTEND and Allocation XABs, 8-10 
SEXTEND buffer requirements, 8-10 
SEXTEND restrictions, 8-11 
SOPEN, 1-22t, 8-lt, 8-12 
SOPEN and Allocation XABs, 8-12 
SOPEN before SEXTEND, 8-14 
SOPEN buffer requirements, 8-12 
SOPEN by file ID, 8-12 
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File organization, 3-43 
File processing options, 3-28 
File revision date, 5-26 
accuracy of, 5-26 
File revision date and time information, 5-21 
File revision number, 5-27 
File sharing, 1-22, 3-52 
allowing readers, 3-52 
allowing writers, 3-52 
and Sequential files, 3-52 
File size, disk. (See File Access Block ALQ field) 
File specification, 3-25 
full, 1-16, 6-3, 6-4 
Maximum full, 6-5 
File, 
add blocks to an RMS-11, 8-10 
close an open RMS-11, 8-2 
create an RMS-1ll, 8-4 
delete an RMS-11, 8-8. (See also SERASE) 
delete records from a Sequential, 8-30 
explanation of locked, 3-30 
locate a specified record in a, 8-19 
logical beginning of a, 8-29 
operation related to an entire, 8-1 
position to end of magnetic tape, 3-29 
replace an existing record in an RMS-ll, 8-31 
retrieve attributes of an RMS-1l1l, 8-12 
supersede existing, 3-29 
temporary, 3-29 
write a new record into an RMS-11, 8-27 
Files and multiblock count, disk sequential, 4-15 
Files, multivolume magnetic tape, 8-25 
Files, record-exists error on relative, 4-26 
Fill number 
data bucket, 5-34 
honor, 4-26 
index bucket, 5-44 
maximum, 5-34, 5-44 
Minimum, 5-34, 5-44 
SFIND. (See macro) 
First data bucket, 5-38 
Fixed control area, 3-32 
maximum, 3-32 
minimum, 3-32 
Fixed-length record format, 3-46 
SFLUSH. (See macro) 
FNA. (See File Access Block) 
FNS. (See File Access Block) 
FOP. (See File Access Block) 
Format 
fixed-length record, 3-46 
record, 3-46 
stream record, 3-46 
undefined record, 3-46 
variable-length record, 3-46 
VFC record, 3-46 
Formats, RMS-1l pool block header, 2-10 
Forms control, FORTRAN, 3-44 
FORTRAN forms control, 3-44 
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Forward or backward, move magnetic tape file, 9-6 
Fragmentation in central buffer pool, 1-6 
FSZ. (See File Access Block) 
Full file specification, 1-16, 6-3, 6-4 
maximum, 6-5 
Generic device characteristics. (See File Access Block DEV field) 
SGET. (See macro) 
Get Space Address (GSA), 1-7 
Get Space Routine, 2-8. (See also GSA routine) 
SGETGSA. (See macro) 
Global 
labels, 1-10 
symbols, 1-10 
SGNCAL. (See macro) 
Greater-than match, 4-26 
Greater-than-or-equal match, 4-26 
GSA, 1-7. (See also Get Space Address) 
GSA routine 
and general registers, 2-10 
controls all buffer space, 2-8 
expected outputs, 2-8 
failure, 2-12 
interface to, 2-9 
Release Core Block, 2-12 
Request Core Block, 2-12 
retrieving address at run time, 2-9 
SRLCB, 2-12 
RMS-11 inputs to, 2-9 
RMS-11 Pool Block Header Formats, 2-10 
RMS-11 release of space, 2-10 
RMS-11 request for space, 2-10 
RMS-11 trusts, 2-8 
RMS-11 use, 2-8 
SROCB, 2-12 
serves all files, 2-8 
specifying address at assembly time, 2-8 
specifying address at run time, 2-9 
symmetrical processing, 2-12 
word boundary, 2-8 
GSAS. (See macro) 
Hard allocation, 5-10 
Header buffer, record, 4-23 
Header formats, RMS-11 pool block, 2-10 
Honor fill numbers, 4-26 
Hundreds of nanoseconds since Nov 17, 1858, 5-23, 5-26 
I/O buffer, 1-6 
calculating requirements, 2-7 
private, 1-6. (See also private buffer pool) 
writes all modified, 8-21 
ID, device 
do not manipulate, 6-2 
used with file ID, 6-2 
ID, file 
do not manipulate, 6-6 
used with device ID, 6-6 
IFAB. (See Internal File Access Block) 
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IFI. (See File Access Block) 
Inconsistent internal conditions, A-18, A-19 
Index 
area number, 5-41 
bucket fill number, 5-44 
bucket size, 5-43 
level area number, lowest, 5-48 
Index of reference, 4-12 
Indexed file 
maximum number of areas in, 5-74 
maximum number of keys in, 5-75 
number of areas in, 5-74 
number of keys in, 5-75 
SINIT. (See macro) 
Initialize user control blocks, 1-2 
SINITIF. (See macro) 
Integer key type 
16-bit signed, 5-36 
32-bit signed, 5-36 
Internal conditions, inconsistent, A-18 
Internal control structures, 1-6 
Internal File Access Block, 1-8, 2-3, 3-34 
Internal Record Access Block, 1-11, 2-4, 2-5, 4-9 
TRAB. (See Internal Record Access Block) 
ISI. (See Record Access Block) 
KBF. (See Record Access Block) 
Key 
and areas in an Indexed file, summary of, 5-71 
Maximum number in an Indexed file, 5-75 
number in an Indexed file, 5-75 
Key buffer size, 4-13 
Key change during update, 5-39 
Key character, null, 5-53 
Key characteristics, 5-39 
and Primary Keys, 5-40 
null, 5-39 
valid combination of, 5-40 
Key data type, 5-36 
and prologue version number, 5-77 
reassembly requirement, 5-36 
Key Descriptors, 2-6 
Key field, 5-28 
Key information, 1-13 
Key length, 5-28 
Key name, 5-46 
length, 5-46 
Key of reference, 4-12, 5-58 
Maximum, 4-12 
Minimum, 4-12 
Key position, 5-28 
Key segments 
maximum number of, 5-52 
minimum number of, 5-52 
multiple, 5-56, 5-61 
number of, 5-52 
position of, 5-56 
Key size, 5-60 
maximum, 5-60 
nonstring, 4-14 
total, 5-63 
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Key type, 5-28 
16-bit signed integer, 5-36 
16-bit unsigned binary, 5-36 
32-bit signed integer, 5-36 
32-bit unsigned binary, 5-36 
string, 5-36 
Key value during random operations, 4-10 
Key value, null, 5-39, 5-53 
Key XAB 
BLN, 5-28t, 5-29 
COD, 5-28t, 5-30 
DAN, 5-28t, 5-31 
DBS, 5-28t, 5-33 
DFL, 5-28t, 5-34 
DTP, 5-28t, 5-36 
DVB, 5-28t, 5-38 
FLG, 5-28t, 5-39 
FLG field contains XBSNUL, 5-53 
IAN, 5-28t, 5-41 
IBS, 5-28t, 5-43 
IFL, 5-28t, 5-44 
KNM, 5-28t, 5-46 
LAN, 5-28t, 5-48 
LVL, 5-28t, 5-50 
MRL, 5-28t, 5-51 
NSG, 5-28t, 5-52 
NUL, 5-28t, 5-53 
NXT, 5-28t, 5-55 
POS, 5-28t, 5-56 
REF, 5-28t, 5-58 
required for Indexed file, 5-28 
RVB, 5-28t, 5-59 
SIZ, 5-28t, 5-60 
TKS, 5-28t, 5-63 
Keys 
key characteristic and Primary, 5-40 
maximum number of, 5-58 
random record operations with string, 4-14 
segmented, 5-52, 5-56 
segmented and ascending byte positions, 5-57 
size of segmented, 5-60 
KRF. (See Record Access Block) 
KSZ. (See Record Access Block) 
Label, 1-8, 1-10, 1-11, 1-13, 1-17, 2-8 
global, 1-10 
LCH. (See File Access Block) 
Least significant bits, 7-1 
Length, key, 5-28 
Length, minimum record, 5-51 
and Alternate Keys, 5-51 
and the Primary Key, 5-5l 
Level number, root, 5-50 
Locate a specified record in a file, 8-19 
Locked file, explanation of, 3-30 
Logical beginning of a file, 8-29 
Logical block number, 3-48, 5-7 


Index-14 


Logical channel, 3-35 


and Record Access Streams, 


maximum, 3-3 

minimum, 3-3 

once assigned, 3-36 
Logical names, 
Logical unit. 


Macro 


as arguments in 


5 
5 


3-21 


3-36 


(See logical channel) 
Lowest index level area number, 5-48 


»-MCALL directive, 


buffer pool declaration, 1-3 


SCLOSE, 


1-8t 


SCOMPARE, 1- 
SCONNECT, 1- 
SCREATE, 1-8 
SDELETE, 1-1 
SDISCONNECT, 
SDISPLAY, l- 


SERASE, 


1-8t 


SEXTEND, 1-8 


FSALQ, 
FSBKS, 
FSBLS, 
FSBPS, 
FSCTX, 
FSDEQ, 
FSDNA, 
FSDNS, 
FSFAC, 
FSFNA, 
FSfnm, 
FSFNS, 
FSFOP, 
FSFSZ, 
FSLCH, 
FSMRN, 
FSMRS, 
FSNAM, 
FSORG, 
FSRAT, 
FSRFM, 
FSRTV, 
FSSHR, 
FSXAB, 
FABSB, 
FABSE, 
FBSBLK, 
FBSCCL, 
FBSCR, 
FBSCTG, 
FBSDEL, 
FBSDFW, 
FBSDLK, 
FBSFID, 
FBSFIX, 
FBSFTN, 
FBSGET, 
FBSIDX, 
FBSMDI, 


3-4 
3-7 
3-10 
3-14 
3-16 
3-18 
3-21 
3-22 
3-24 
3-26 
1-10 
3-27 
3-30 
3-32 
3-35 
3-38 
3-40 
3-42 
3-43 
3-45 
3-47 
3-49, 
3-53 
3-56 
1-3, 
1-8 
3-44 
3-19 
3-44 
3-28 
3-23 
3-29 
3-29 
3-29 
3-46 
3-44 
3-23 
3-43 
3-19 


, 8-2 
18, 7-2 


10t, 8-16 


ty 8-4 


Ot, 8-17 


1-10t, 
8t, 8-6 
, 8-8 
t, 8-10 


3-51 


1-8 
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Macro (continued) 
FBSMKD, 3-29 
FBSNEF, 3-29 
FBSPOS, 3-29 
FBSPUT, 3-23 
FBSREA, 3-23, 9-1 
FBSREC, 3-19 
FBSREL, 3-43 
FBSRWC, 3-29 
FBSRWO, 3-29 
FBSSDI, 3-19 
FBSSEQ, 3-43 
FBSSQD, 3-19 
FBSSTM, 3-46 
FBSSUP, 3-29 
FBSTMD, 3-29 
FBSTMP, 3-30 
FBSTRM, 3-19 
FBSTRN, 3-23 
FBSUDF, 3-46 
FBSUPD, 3-24 
FBSVAR, 3-46 
FBSVFC, 3-46 
FBSWRI, 3-52, 9- 
FBSWRT, 3-24 
SFETCH, 1-18, 7-4 
field access, 1-3, 3-1, 4-1, 5-1, 6-1 
file operation, 1-21 
SFIND, 1-10t, 8-19 
SFLUSH, 1-10t, 8-21 
SFREE, 8-22 
SGET, 1-10t, 8-23 
SGETGSA, 2-9 
SGNCAL, 1-3 
GSA$, 2-8 
SINIT, 1-2, 1 
SINITIF, 1-2, 
NSESA, 6-3 
NSESS, 6-5 
NSfnm, 1-17 
NAMSB, 1-3, 1-17 
NAMSE, 1-17 
SNXTVOL, 1-10t, 8-25 
SOFF, 1-18, 7-6 
SOPEN, 1-8t, 8-12 
ORGS, 1-3 
PSBDB, 1-7t, 2-lt, 2- 
PSBUF, 1-7t, 2-lt, 2- 
PSFAB, 1-7t, 2-lt, 2- 

2- 
2- 


1 


-3 
1-3 


PSIDX, 1-7t, 2-1t, 
PSRAB, 1-7t, 2-lt, 
PSRABX, 1-7t, 2-lt, 2-5 
POOLSB, 1-3, 1-7t, 2-1t 
POOLSE, 1-7t, 2-1t 
processing, 1-l 

SPUT, 1-10t, 8-27 
RSBKT, 4-4 

RSCTX, 4-6 

RSFAB, 4-7 


m DW ~) 
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Macro (continued) 
RSKBF, 4-11 
RSKRF, 4-12 
RSKSZ, 4-14 
RSMBC, 4-15 
RSMBF, 4-17 
RSRAC, 4-19 
RSRBF, 4-21 
RSRFA, 4-22 
RSRHB, 4-24 
RSRSZ, 4-29 
RSUBF, 4-33 
RSUSZ, 4-34 
RABSB, 1-3, 1-11 
RABSE, 1-11 
RBSASY, 4-25 
RBSEOF, 4-25 
RBSFDL, 4-25 
RBSKEY, 4-19 - 
RBSKGE, 4-26 
RBSKGT, 4-26 
RBSLOA, 4-26 
RBSMAS, 4-26 
RBSRFA, 4-19 
RBSSEQ, 4-19 
RBSUIF, 4-26 
record operation, 1-22 . 
SREWIND, 1-10t, 8-29 
SSET, 1-18, 7-7 
SSETGSA, 2-9 
SSTORE, 1-18, 7-9 
STESTBITS, 1-18, 7-11 
STRUNCATE, 1-10t, 8-30 
SUPDATE, 1-10t, 8-31 
SWAIT, 8-33 
XSAID, 5-4 
XSALN, 5-7 
XSALQ, 5-9 
XSAOP, 5-10 
XSBKZ, 5-11 
XSDAN, 5-32 
XSDEQ, 5-16 
XSDFL, 5-35 
XSDTP, 5-37 
XSFLG, 5-40 
XSfnm, 1-14 
XSIAN, 5-42 
XSIFL, 5-45 
XSKNM, 5-47 
XSLAN, 5-49 
XSLOC, 5-18 
XSNUL, 5-53 
XSNXT, 5-19, 5-25, 5-55, 5-67, 5-76 
XSPOS, 5-57 
XSPRG, 5-68 
XSPRJ, 5-69 
XSPRO, 5-71 
XSREF, 5-58 
XSSIZ, 5-61 
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Macro (continued) 
XABSB, 1-3, 1-13 
XABSE, 1-13 
XBSALL, 1-13 
XBSBN2, 5-36 
XBSBN4, 5-36 
XBSCHG, 5-39 
XBSCTG, 5-10 
XBSCYL, 5-7 
XBSDAT, 1-13 
XBSDUP, 5-39 
XBSHRD, 5-10 
XBSIN2, 5-36 
XBSIN4, 5-36 
XBSKEY, 1-13 
XBSLBN, 5-7 
XBSNUL, 5-39 
XBSPRO, 1-13 
XBSSTG, 5-36 
._ XBSSUM, 1-13 
XBSVBN, 5-7 
Macros 
file operation, 1-21 
record operation, 1-22 
Magnetic tape block size. (See File Access Block BLS field) 
Maximum, 3-10 
minimum, 3-10 
Magnetic tape block, characters in. (See File Access Block BLS field) 
Magnetic tape file 
move forward or backward, 9-6 
multivolume, 8-25 
position to end of, 3-29 
rewind on close, 3-29 
rewind on open, 3-29 
Magnetic tape, ANSI, 3-24 
Marked for delete 
permanent file, 3-29 
temporary file, 3-29 
Mass Insert, 4-26 
Match criterion, 4-13 
approximate, 4-13 
exact, 4-13 
greater-than, 4-26 
greater-than-or-equal, 4-26 
Max imum 
allocation quantity, 3-4 
area number, 5-31, 5-41, 5-48 
bucket size, 3-6, 5-11 
clustersize, 3-50 
default extension quantity, 3-18, 5-15 
default name string, 3-22 
file name string size, 3-27 
fill number, 5-34, 5-44 
fixed control area, 3-32 
full file specification, 6-5 
key of reference, 4-12 
key size, 5-60 
logical channel, 3-35 
magnetic tape block size, 3-10 
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Maximum (continued) 
multiblock count, 4-15 
multibuffer value, 4-17 
number of areas, 5-4 
number of areas in an Indexed file, 5-74 
number of key segments, 5-52 
number of keys, 5-58 
number of keys in an Indexed file, 5-75 
programmer number, 5-68 
project number, 5-69 
Record Number 
Record Number, minimum, 3-37 
Record Size, 3-39, 4-28 
Record Size and fixed-length records, 3-40 
Record Size and Relative files, 3-40 
user buffer size, 4-34 
virtual block number, 4-4 
window size, 3-48 
MBC. (See Record Access Block) 
MBF. (See Record Access Block) 
-MCALL directives, 1-2 
general form, 1-3 
minimizing number of directives, 1-3 
minimum set of arguments, 1-3t 
omitting macro names, 1-4 
use across modules, 1-4 
Minimum 
allocation quantity, 3-4 
bucket size, 3-6, 5-11 
clustersize, 3-50 
default extension quantity, 3-17, 5-15 
fill number, 5-34, 5-44 
fixed control area, 3-32 
key of reference, 4-12 
logical channel, 3-35 
magnetic tape block size, 3-10 
Maximum Record Number, 3-37 
number of areas, 5-4 
number of key segments, 5-52 
record length, 5-51 
record length and Alternate Keys, 5-51 
record length and the Primary Key, 5-51 
record size, 3-39 
window size, 3-48 
Mode during record operation, access, 4-19 
Mode 
Random Access, 4-19 
Record Transfer, 4-20 
Sequential Access, 4-19 
Modified I/O buffers, writes all, 8-21 
Module, Root, 1-5 
Move magnetic tape file forward or backward, 9-6 
Moved by record operation, record, 4-20 
MRN. (See File Access Block) 
MRS. (See File Access Block) 
Multiblock. count, 4-15 
and I/O buffer size, 4-16 
disk sequential files and, 4-15 
maximum, 4-15 
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Multibuffer, 4-17 
and I/0 buffer size, 4-18 
and Indexed files, 4-17 
and minimum buffer requirements, 4-18 
and Relative files, 4-17 
maximum value, 4-17 
waste of address space, 4-18 
Multiple key segments, 5-56, 5-61 
Multivolume magnetic tape files, 8-25 
NSfnm. (See macro) 
NAM, (See File Access Block) 
NAM Block, 1-1, 1-16, 6-1 
allocation, 1-17 
allocation macros, 1-3 
and the FAB, 3-41 
cautions, 1-17 
DVI, 1-18, 6-lt, 6-2 
ESA, 1-18, 6-l1t, 6-3 
ESA and open/erase by file ID, 6-3 
ESL, 1-18, 6-lt, 6-4 
ESS, 1-18, 6-1lt, 6-5 
FID, 1-18, 6-lt, 6-6 
field offset macros, 1-3, 6-1 
indicate existence of, 1-16 
initialization, 1-17 
initialization macros, 1-3, 6-1 
Name Block. (See NAM Block) 
Name string, default, 3-20 
and logical names, 3-21 
contents, 3-20 
Maximum size, 3-22 
notation, 3-21 
size, 3-22 : 
Name string, expanded file 
address, 6-3 
length from RMS-11, 6-4 
size from your program, 6-5 
Name string, file 
address, 3-25 
conform to system standards, 3-26 
maximum size, 3-27 
notation, 3-25 
parsing under RSTS/E, 3-26 
size, 3-27 
use in file specification, 3-25 
Name, key, 5-46 
length, 5-46 
Names, logical, 3-21 
Nanoseconds since Nov 17, 1858, hundreds of, 5-23, 5-26 
New record into an RMS-11 file, write a, 8-27 
Next record, 1-22 
Next tape volume, continue processing on the, 8-25 
Nonstring key size, 4-14 
Nov 17, 1858, hundreds of nanoseconds since, 5-23, 5-26 
Null key character, 5-53 
Null key characteristic, 5-39 
Null key value, 5-39, 5-53 
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Number of 
areas in an Indexed file, 5-74 
bytes in a bucket, calculating, 5-34, 5-44 
key segments, 5-52 
key segments, maximum, 5-52 
key segments, minimum, 5-52 
keys in an Indexed file, 5-75 
keys, maximum, 5-58 
Number 
cylinder, 5-7 
data bucket fill, 5-34 
device cluster, 5-7 
file revision, 5-27 
honor fill, 4-26 
index bucket fill, 5-44 
Logical Block, 3-48, 5-7 
maximum fill, 5-34, 5-44 
maximum programmer, 5-68 . 
maximum project, 5-69 
Maximum Record 
maximum virtual block, 4-4 
minimum fill, 5-34, 5-44 
minimum Maximum Record, 3-37 
Programmer, 5-68 
project, 5-69 
prologue version, 5-77 
prologue version, and key data types, 5-77 
relative record, 4-4, 4-10, 4-13 
relative volume, 5-20 
root level, 5-50 
Root Virtual Block, 5-59 
Virtual Block, 3-48, 5-7, 5-38 
Numeric value, 1-10 
SNXTVOL. (See macro) 
Octal radix, 1-18, 7-1 
SOFF. (See macro) 
SOPEN. (See macro) 
Open, rewind magnetic tape file on, 3-29 
Opened for write operations by RMS-1ll, file, 5-27 
Operating systems, PDP-1ll, 1-1 
Operation macros 
file, 1-21 
record, 1-22 
Operation 
access mode during record, 4-19 
asynchronous record, 1-22, 4-25 
calling sequence, 1-20 
file, 1-2, 1-19 
key value during random, 4-10 
optional functions during record, 4-25 
random record, with string keys, 4-14 
record, 1-2, 1-19 
record moved by record, 4-20 
related to an entire file, 8-1 
set proper field values before, 1-19 
suspend program, 8-33 
synchronous record, 1-22 
valid file, 3-23 
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Optimize buffer space, 4-25 
Optional functions during record operations, 4-25 
Options 
allocation, 5-10 
file processing, 3-28 
ORG. (See File Access Block) 
ORGS, 1-3, 1-5. (See also macro) 
CRE, 1-5 
DEL, 1-5 
FIN, 1-5 
for each file organization, 1-5 
general form, 1-5 : 
GET, l- 
IDX, 1 
PUT, l- 
REL, l- 
SEQ, l 
UPD, 1 
use, 1-5 
Organization, file, 3-43 
Outstanding asynchronous record operation, 8-33 
Overlays, 1-22 
PDP-1l1 operating systems, 1-1 
Performance Report, Software, A-19 
Placement control, 5-6 
location, 5-17 
RSTS/E restriction, 5-7 
Pointers, retrieval, 3-48 
Pool block header formats, RMS-1l, 2-10 
Pool, central buffer. (See central buffer pool) 
Pool, private buffer (See private buffer pool) 
Position of key segments, 5-56 
Position to end of magnetic tape file, 3-29 
Position, key, 5-28 
Primary Keys, key characteristic and, 5-40 
Printer, 3-45 
Private buffer pool 
address, 3-1l 
address on word boundary, 3-11 
and central buffer pool, 3-12 
calculating size of, 3-13 
your program's use of, 3-12 
Private I/O buffer, 1-6. (See also private buffer. pool) 
Processing 
bypass RMS-11l record, 9-l 
continue on the next tape volume, 8-25 
environment, 1-2 
existing file available for, 8-12 
options, file, 3-28 
Program operation, suspend, 8-33 
Programmer number, 5-68 
Maximum, 5-68 
Project number, 5-69 
maximum, 5-69 
Prologue version number, 5-77 
and key data types, 5-77 
Protection code, 5-64 
programmer number, 5-68 
project number, 5-69 
values, 5-70 
Protection information, 1-13 
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Protection XAB 
BLN, 5-64t, 5-65 
COD, 5-64t, 5-66 
NXT, 5-64t, 5-67. 
PRG, 5-64t, 5-68 
PRJ, 5-64t, 5-69 
PRO, 5-64t, 5-70 
SPUT. (See macro) 
Put operation, automatic file extension during, 3-17 
Quantity 
allocation. (See allocation quantity) 


default extension. (See default extension quantity) 


file default extension, 3-18 
maximum allocation, 3-4 
Maximum default extension, 3-18, 5-15 
minimum allocation, 3-4 
Minimum default extension, 3-17, 5-15 
RSfnm. (See macro) 
RAB. (See Record Access Block) 
RAC, (See Record Access Block) 
Radix 
decimal, 1-2, 1-10 
octal, 1-18, 7-1 
Random Access Mode, 4-19 
Random record operations 
key value during, 4-10 
with string keys, 4-14 
RAT. (See File Access Block) 
RBF. (See Record Access Block) 
Read-sharing, 3-52 
Record Access Block, 1-1, 1-10, 4-1 
allocation, 1-11 
allocation macros, 1-3 
and a FAB, 4-7 
associated with a FAB, 8-16 
ASYN, 1-11 ; 
asynchronous, 4-25 
BID, 1-12t, 4-2t, 4 
BKT, 1-12t, 4-2t, 4 
BLN, 1-12t, 4-2t, 4- 
cautions, 1-12 
CTX, 1-12t, 4-2t, 4 
FAB, 1-12t, 4-2t, 4 
field offset macros, 1-3, 4-1 
initialization, 1-11 
initialization macros, 1-3, 4-1 
ISI, 1-12t, 4-2t, 4-9 
KBF, 1-12t, 4-2t, 4-10 
KRF, 1-12t, 4-2t, 4-12 
KSZ, 1-12t, 4-2t, 4-13 
MBC, 1-12t, 4-2t, 4-15 
MBF, 1-12t, 4-2t, 4-17 
RAC, 1-12t, 4-2t, 4-19 
RBSLOA, 5-34, 5-44 
RBF, 1-12t, 4-2t, 4-20 
representing more than one Record, 1-11 
RFA, 1-12t, 4-2t, 4-22 
RHB, 1-12t, 4-2t, 4-23 
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Record Access Block (continued) 
ROP, 1-l2t, 4-2t, 4-25 
RSZ, 1-12t, 4-2t, 4-28 
STS, 1-12t, 4-2t, 4-30 
STV, 1-12t, 4-2t, 4-31 
SYN, 1-11 
type, 1-11 
UBF, 1-12t, 4-2t, 4-32 
use of RBF/RSZ during processing, 4-21 
USZ, 1-12t, 4-2t, 4-34 
Record Access Stream, 1-22 
disconnect all, 8-2 
establish a, 8-16 
terminate a, 8-18 
unlocks a bucket for, 8-22 
Record attributes, 3-44 
Record-exists error on Relative files, 4-26 
Record format, 3-46 
fixed-length, 3-46 
stream, 3-46 
undefined, 3-46 
variable-length, 3-46 
VFC, 3-46 
Record header buffer, 4-23 
Record length, minimum, 5-51 
and Alternate Keys, 5-51 
and the Primary Key, 5-51 
Record Management Service, 1-1 
Record Number, Maximum (Relative files only), 3-37 
minimum, 3-37 
Record number, relative, 4-4, 4-10, 4-13 
Record operation, 1-2, 1-19 
calling sequence, 1-20 
connect, 4-7 
SDELETE, 3-23 
SGET, 3-23 
greater-than match, 4-26 
greater-than-or-equal match, 4-26 
input key, 4-10 
SPUT, 3-23 
relative record number input, 4-4 
RMS-11 verifies RAB before, 4-3, 4-5 
STRUNCATE, 3-23 
SUPDATE, 3-24 
Record Operation Macros, 1-22, 8-15 
SCONNECT, 1-23t, 8-15t, 8-16 
SDELETE, 1-23t, 8-15t, 8-17 
SDELETE and Current Record, 8-17 
SDELETE and Sequential file, 8-17 
SDISCONNECT, 1-23t, 8-15t, 8-18 
SDISCONNECT and magnetic tape file, 8-18 
SFIND, 1-23t, 8-15t, 8-19 
SFIND and duplicate keys, 8-20 
SFIND and ERSRNF error code, 8-20 
SFIND and index of reference, 8-20 
SFLUSH, 1-23t, 8-15t, 8-21 
SFREE, 1=23t, 8-15t, 8-22 
SFREE and multiple streams, 8-22 
SGET, 1-23t, 8-15t, 8-23 
SGET and duplicate keys, 8-24 
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Record Operation Macros (continued) 
SGET and ERSRNF error code, 8-24 
SGET and RAB RBF/RSZ fields, 8-23 
SGET and unit record terminator, 8-24 
SNXTVOL, 1-23t, 8-15t, 8-25 
SNXTVOL and input file processing, 8-25 
SNXTVOL and output file processing, 8-25 
SPUT, 1-23t, 8-15t, 8-27 
SPUT and Indexed files, 8-28 
SPUT and Next Record, 8-27 
SPUT and Relative files, 8-28 
SPUT and Sequential files, 8-28 
SREWIND, 1-23t, 8-15t, 8-29 
SREWIND and RSTS/E magnetic tape, 8-29 
STRUNCATE, 1-23t, 8-15t, 8-30 
STRUNCATE and Current Record, 8-30 
STRUNCATE and Next Record, 8-30 
SUPDATE, 1-23t, 8-15t, 8-31 
SUPDATE and Current Record, 8-31 
SUPDATE and RAB RBF/RSZ fie, 8-31 
SUPDATE restrictions on Indexed files, 8-32 
SUPDATE restrictions on Relative files, 8-32 
SUPDATE restrictions on Sequential files, 8-32 
SWAIT, 1-23t, 8-15t, 8-33 
Record operation 
access mode during, 4-19 
asynchronous, 1-22, 4-25 
optional functions during, 4-25 
random with string keys, 4-14 
record moved by, 4-20 
synchronous, 1-22 
Record processing, bypass RMS-l1l, 9-1 
Record size, 4-28 
input to put operation, 4-29 
input to update operation, 4-29 
Record size, maximum, 3-39, 4-28 
and fixed-length records, 3-40 
and Relative files, 3-40 
Record size, minimum, 3-39 
Record Transfer Mode, 4-20 
Locate, 4-26 | 
Record's File Address, 4-19, 4-22, 8-19, 8-23 
and disk files, 8-20, 8-24 
Record 
Current, 1-22 
delete an existing, 8-17 
Next, 1-22 
retrieve a specified, 8-23 
delete from a Sequential file, 8-30 
Reference, key of, 5-58 
Maximum, 4-12 
minimum, 4-12 
Relative files, record-exists error on, 4-26 
Relative record number, 4-4, 4-10, 4-13 
Relative volume number, 5-20 
Release buffer space, 8-18 
Release Core Block. (See GSA routine) 
Release of space, RMS-11, 2-10 
Replace an existing record in an RMS-11 file, 8-31 
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Report, Software Performance, A-19 
Request Core Block. (See GSA routine) 
Request for service, 1-2 
Request for space, RMS-ll, 2-10 
Reset bits within a bit string data field, 7-6 
Retrieval pointers, 3-48 
Retrieval window size, 3-48 
Retrieve 
a specified record, 8-23 
a specified virtual block, 9-3 
attributes of an RMS-1l file, 8-12 
Revision date and time information, file, 5-21 
Revision date, file, 5-26 
accuracy of, 5-26 
Revision number, file, 5-27 
SREWIND. (See macro). 
Rewind magnetic tape file 
on close, 3-29 
on open, 3-29 
RFA. (See Record Access Block) 
RFA, access by, 4-19 
RFM. (See File Access Block) 
RHB. (See Record Access Block) 
SRLCB. (See GSA routine) 
RMS-11, 1-1 
facilities, declare, 1-2 
Pool Block Header Formats, 2-10 
release of space, 2-10 
request for space, 2-10 
Root level number, 5-50 
Root module, 1-5 
Root Virtual Block Number, 5-59 
ROP. (See Record Access Block) 
Routine, fatal error crash, A-2 
and general registers, A-18 
ERSBUG error code, A-19 
ERSFAB error code, A-18 
ERSMAP error code, A-19 
ERSRAB error code, A-18 
Routines, completion, 1-19 
SRQCB. (See GSA routine) 
RSTS/E, file extension and clustersize on, 3-18, 5-16 
RSZ. (See Record Access Block) 
RTV. (See File Access Block) 
Segmented keys, 5-52, 5-56 
and ascending byte positions, 5-57 
size of, 5-60 
maximum number of segments, 5-52 
minimum number of segments, 5-52 
Segments 
multiple key, 5-56, 5-61 
number of key, 5-52 
position of key, 5-56 
Sequencing of Allocation XABs, 5-4 
Sequential Access Mode, 4-19 
Sequential file 
delete records from a, 8-30 
and multiblock count, 4-15 
Service, request for, 1-2 
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SSET. (See macro) 
Set bits within a bit string data field, 7-7 
Set context, 8-29 
at end-of-file during connect, 4-25 
SSETGSA. (See macro) 
Severe error conditions, A-2 
Sharing, file, 1-22, 3-52 
allowing readers, 3-52 
allowing writers, 3-52 
and Sequential files, 3-52 
SHR. (See File Access Block) 
Signed integer key type 
16-bit, 5-36 
32-bit, 5-36 
Significant bits, least, 7-1 
Size of segmented keys, 5-60 
Size, bucket, 4-17, 5-9, 5-11, 5-16, 5-49 
and default extension quantity, 3-17, 5-15 
and initial allocation quantity, 3-4, 5-8 
valid for Relative and Indexed files only, 3-6 
(See also File Access Block BKS field) 
(See also Allocation XAB BKZ field) 
Size 
advantage of different bucket, 5-12 
data. bucket, 5-33 
disk file. (See Allocation XAB ALQ field) 
index bucket, 5-43 
key, 5-60 
key buffer, 4-13 
magnetic tape block. (See File Access Block BLS field) 
maximum bucket, 3-6, 5-11 
maximum file name string, 3-27 
maximum key, 5-60 | 
maximum magnetic tape block, 3-10 
Maximum Record, 3-39, 4-28 
Maximum Record, and fixed-length records, 3-40 
Maximum Record, and Relative files, 3-40 
maximum user buffer, 4-34 
maximum window, 3-48 
minimum bucket, 3-6, 5-11 
minimum magnetic tape block, 3-10 
minimum record, 3-39 
minimum window, 3-48 
nonstring key, 4-14 
recommended for magnetic tape blocks, 3-9 
record, 4-28 
record, input to put operation, 4-29 
record, input to update operation, 4-29 
retrieval window, 3-48 
total key, 5-63 
user buffer, 4-32, 4-34 
Smithsonian Astrophysical Base Date, 5-23, 5-26 
Software Performance Report, A-19 
Space, buffer. (See also central buffer pool) 
optimize, 4-25 
release, 8-18 
RMS~11 release of, 2-10 
RMS-11 request for, 2-10 
Spanning, block, 3-44 
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Specification, full file, 1-16, 6-3, 6-4 
Specification, maximum full file, 6-5 
Status code, 3-54, 4-30 
Status value, 3-55, 4-31, A-2 
description of system error codes, A-4 
SSTORE. (See macro) 
Store file attributes in XAB fields, 8-6 
Stream. (See Record Access Stream) 
Stream record format, 3-46 
String key type, 5-36 
String keys, ‘random record operations with, 4-14 
String size, maximum file name, 3-27 
Structures, internal control, 1-6 
STS. (See Record Access Block) 
STV. (See Record Access Block) 
STV field, A-2 
SUScod, A-1l 
Success completion codes, A-1l 
Summary information, 1-13 
Summary of keys and areas in an Indexed file, 5-71 
Summary XAB 
BLN, 5-71t, 5-72 
COD, 5-71t, 5-73 
NOA, 5~-71t, 5-74 
NOK, 5-71t, 5-75. 
NXT, 5-71t, 5-76 
PVN, 5=71t, 5-77 
Supersede existing file, 3-29 
Suspend program operation, 8-33 
Symbolic value, 1-10 
Symbols, global, 1-10 
Synchronous record operation, 1-22 
System defaults, 1-16, 3-25 
Systems, PDP-11l operating, 1-1 
Tape block size, magnetic. (See File Access Block BLS field) 
recommended, 3-9 
Maximum, 3-10 
minimum, 3-10 
Tape block, characters in magnetic. (See File Access Block) 
Tape file forward or backward, move magnetic, 9-6 
Tape files, multivolume magnetic, 8-25 
Tape volume, continue processing on the next, 8-25 
Task build, 1-2 
Task Builder, 1-5, 1-22 
PSECTS in alphabetical order, 1-23 
/8Q switch, 1-23 
Temporary file, 3-29 
Temporary file marked for delete, 3-29 
Terminal, 3-45 
Terminate a Record Access Stream, 8-18 
STESTBITS. (See macro) 
Time information 
file creation date and, 5-21 
file revision date and, 5-21 
Total key size, 5-63 
Transfer mode, record, 4-20 
STRUNCATE. (See macro) 
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Type, key, 5-28 
16-bit signed integer key, 5-36 
16-bit unsigned binary key, 5-36 
32-bit signed integer key, 5-36 
32-bit unsigned binary key, 5-36 
and prologue version number, 5-77 
key data, 5-36 
reassembly requirement, 5-36 
string key, 5-36 
UBF. (See Record Access Block) 
Undefined record format, 3-46 
Unit record device, 3-45 
Unit, logical. (See logical channel) 
Unlock file if abnormal close, 3-29 
Unlocks a bucket for a Record Access Stream, 8-22 
Unsigned binary key type 
16-bit, 5-36 
32-bit, 5-36 
SUPDATE. (See macro) 
Update operation 
automatic file extension during, 3-17 
key change during, 5-39 
User buffer, 8-23 
User buffer size, 4-34 
and Locate Mode, 4-32 
maximum, 4-34 
User call error, fatal, A-18 
User context field. (See Record Access Block CTX field) 
User control block 
access fields in, 1-2 
allocate, 1-2 
allocation at assembly time, 1-8 
assembly-time field initialization, 1-8 
data fields in, 1-8 
initialize, 1-2 
other than default value in field, 1-10 
run-time field access, 1-8 
(See also File Access Block) 
(See also Record Access Block) 
(See also Extended Attribute Block) 
(See also NAM Block) 
USZ. (See Record Access Block) 
Variable-length record format, 3-46 
Variable-with-fixed-control. (See VFC) 
Version number, prologue, 5-77 
and key data types, 5-77 
VFC.. 
and no record header buffer, 4-23 
and scatter-read, gather-write, 4-23 
during Locate Mode, 4-24 
record format, 3-46 
records, 3-32, 4-23 
Virtual block number, 3-48, 5-7, 5-38 
maximum, 4-4 
Root, 5-59 
Virtual block 
retrieve a specified, 9-3 
write a specified, 9-5 
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Volume number, relative, 5-20 
Volume, continue processing on the next tape, 8-25 
Wait for asynchronous record operation, 8-33 
Window size 

maximum, 3-48 

minimum, 3-48 

retrieval, 3-48 
Write 

a new record into an RMS-11 file, 8-27 

a specified virtual block, 9-5 

operations by RMS-11, file opened for, 5-27 
Write-sharing, 3-52 
Writes all modified I/O buffers, 8-21 
XSfinm. (See macro) 
XAB. (See File Access Block) 
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READER’S COMMENTS 


Did you find this manual understandable, usable, and well-organized? Please make suggestions for improvement. 





Did you find errors in this manual? If so, specify the error and the page number. 





Please indicate the type of user/reader that you most nearly represent. 








O = Assembly language programmer 
C1 —Higher-level language programmer 
O ~—— Occasional programmer (experienced) 
O User with little programming experience 
O Student programmer 
Ol = Other (please specify) 
Nari Ga Dat 
Organization 
Street 
City 222 ee Sate Zip ‘Code 


or 
Country 
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